anchor.diff:  * `id` for the entity ID, represented by a JSON string. If the entity has an `id` attribute itself it will be ignored.
   * `type` for the entity type, represented by a JSON string. If the entity has a `type` attribute itself it will be ignored.
     If the entity doesn't have a type, then this property is not included.
  -* A collection of properties, one per entity attribute. Property values can be single values or they can include,
  -  `type` and properties representing metadata as well. Property values which correspond to the primitive JSON datatypes
  -  "string", "number" and "boolean" and with no metadata are rendered as regular JSON values. Property values
  -  which specify a custom type or include metadata are rendered as JSON objects with the following properties:
  -  * `value`: for the attribute value, rendered as a regular JSON value depending on the type. Attributes with an
  -    user-defined informative types are rendered as JSON strings (TBD).
  -  * `type`: a JSON string which represents the attribute type provided at attribute creation time.
  -  * A collection of properties one per metadata field associated to the attribute value. Metadata properties follow the
  -    same representation rules that applies to properties which represent attributes (except that a metadata
  -    cannot have metadata properties). 
  -
  -Canonical format description (TBD).
  -
  -### Predefined types
  -
  -All attribute types not included in the list below are considered *user-defined informative* types. The values of
  -user-defined informative types are represented by JSON string.
  -
  -* `number` (or `Number`):  identifies numbers, either integer or float.
  -They are associated to JSON number type (see https://developer.mozilla.org/en-US/docs/Glossary/Number).
  -Operators allowed are: greater than, lesser than, greater or equal, lesser or equal and range.
  +* A collection of properties, one per entity attribute. Properties representing attributes with no metadata
  +  or type are rendered as regular JSON values. Properties representing attributes which specify a type or include
  +  metadata are rendered as JSON objects with the following properties:
  +  * `value`: for the attribute value, rendered as a regular JSON value (string, number or boolean), object or array.
  +  * `type`: a JSON string which represents the user-defined NGSI attribute type.
  +  * A collection of properties one per metadata field associated to the attribute value. Metadata properties follow
  +    the same representation rules that applies to properties which represent attributes (except that a metadata
  +    cannot have metadata properties).
  +
  +### Special attribute types
  +
  +Generally speaking, user-defined attribute types are informative, they are processed by the NGSIv2 server in
  +an opaque way. Nonetheless, the types described below are used to convey an special meaning
  +
  +* `date`:  identifies dates, in ISO8601 format. These attributes can be used with the
  +  greater than, lesser than, greater or equal, lesser or equal and range query operators. Eg:
   
   ```
  -"temperature": 32.5
  +  "timestamp": {
  +    "value": "2017-06-17T07:21:24.238Z",
  +    "type: "date"
  +  }
   ```
   
  -* `string` (or `String`): identifies text string. They are represented by JSON strings (see https://developer.mozilla.org/en-US/docs/Glossary/String).
  +* `geo:point`: identifies the location of the entity in geo-location queries. If an entity have several attributes
  +  of this type all them define a possible location for the entity from a geo-location query point of view. (TBD:
  +  check feasibility).
   
   ```
  -"msg": "Hello world"
  -```
  -
  -* `boolean` (or `Boolean`): identifies a logical value, either true or false. They are represented by JSON booleans (see https://developer.mozilla.org/en-US/docs/Glossary/Boolean).
  -
  -```
  -"active": true
  -```
  -
  -* `date` (or `Date`):  identifies dates, in ISO8601 format. They are represented by JSON strings. Operators allowed are:
  -greater than, lesser than, greater or equal, lesser or equal and range.
  -
  -```
  -"timestamp": "2017-06-17T07:21:24.238Z"
  -```
  -
  -
  -* `geo:point`: identifies a geolocation. They are represented by JSON strings. An
  -entity can only have one `geo:point` attribute (TBD: this is yet under discussion, one possibility is
  -there can be multiple points associated to an entity but an entity can only be located on one place).
  -
  -```
  -{
  -  ...
     "location": {
       "value": "41.3763726, 2.1864475,14",
       "type": "geo:point"
     }
  +```
  +
  +### Canonical format description
  +
  +This is a variant of the represention format aimed at clients that need a regular representation of the entities
  +and attributes, that can be used in the operations that support the `canonical` option.
  +
  +* Entity `type` is mandatory. If the entity has no type, JSON `null` is used.
  +* Property `attrs` is mandatory and includes a JSON object for the attributes.
  +* Each attribute is described always with `value`, `type` and `metadata`. All fields are mandatory (attributes
  +  without type use JSON `null` for that property).
  +* Each metadata is described always with `value` and `type`. Both fields are mandatory (metadata
  +  without type use JSON `null` for that property).
  +
  +```
  +{
  +  "type": "Room",
  +  "id": "Boe_Idearium",
  +  "attrs": {
  +    "speed": {
  +      "value": 88,
  +      "type": null,
  +      "metadata": { }
  +    },
  +    "pressure": {
  +      "value": 12.1,
  +      "type": null,
  +      "metadata": { }
  +    },
  +    "temperature": {
  +      "value": 22,
  +      "type": "urn:phenomenum:temperature",
  +      "metadata": { }
  +    },
  +    "colour": {
  +      "value": "black",
  +      "type": "myString",
  +      "metadata": { }
  +    }
  +  }
   }
   ```
   
  -At creation or update time, the type has to be coherent with the value of the attribute, e.g the following
  -will result in an error response:
  -
  -(TBD: this behaviour is under discussion, specially the case for the "myType" with JSON number for the value)
  -
  -```
  -{
  -  "value": "23.5", -> value should be: 23.5
  -  "type": "number"
  -}
  -
  -
  -{
  -  "value": 23.5,   -> value should be: "23.5"
  -  "type": "string"
  -}
  -
  -{
  -  "value": "23.5", -> value should be: "23.5" (user defined types always use JSON strings as value)
  -  "type": "myType"
  -}
  -
  -{
  -  "value": "foo, bar", -> it is not correctly formated as coordinates
  -  "type": "geo:point"
  -}
  -```
  -
   ## Error responses
   
   In the case of being present, the error payload is JSON object including the following fields:
   
   * `error` (mandatory): a textual description of the error.
   * `description` (optional): additional information about the error.
  +
  +Error list (HTTP response code in paranthesis):
  +
  +* NotFound (404). The context element referred in the request has not been found.
  +* TooManyResults (409). There are several results that match with the resource identification used
  +  in the request. This typically the case of requesting an entity with not enough information and the
  +  solution is to enhance entity identification adding more information, e.g. adding entity type
  +  and/or service path.
   
   ## API Entry Point [/v2]
   
  
positive.code: 
  + Response 200
  
  ## Entity types [/v2/types{?limit,offset,options}]
  
  ### Retrieve entity types [GET /v2/types/{?limit,offset,options}]
  
negative.code: 
  + Response 200
  
  <!--
  
  ## Attribute Value by Entity type and ID [/v2/entities/type/{entityType}/id/{entityId}/attrs/{attrName}/value{?options}]
  
  ### Get attribute data [GET /v2/entities/type/{entityType}/id/{entityId}/attrs/{attrName}/value{?options}]
  