Data models guidelines

This is a set of guidelines for defining new data models.

Syntax

Use English terms, preferably American English.
Use camel case syntax for attribute names (camelCase).
Entity type names must start with a Capital letter, for instance, WasteContainer.
Use names and not verbs for attribute names, ex. name, qualifying it when necessary, ex. totalSpotNumber or dateCreated.
Avoid plurals in attribute names, but state clearly when a list of items fits. Ex. category.

Check for the existence of the same attribute on any of the other models and reuse it, if pertinent.
Have a look at schema.org trying to find a similar term with the same semantics.
Try to find common used ontologies or existing standards well accepted by the Community, or by goverments, agencies, etc. For instance, Open311 for civic issue tracking or Datex II for transport systems.

When possible reuse schema.org data types (Text, Number, DateTime, StructuredValue, etc.).

Enumerate the allowed values for each attribute. Generally speaking it is a good idea to leave it open for applications to extend the list, provided the new value is not semantically covered by any of the existing ones.
State clearly what attributes are mandatory and what are optional. If needed state clearly what is the meaning of a null value.

Define a default unit for magnitudes. Normally it will be the unit as stated by the international system of units.
If a quantity is expressed in a different unit than the default one, use the unitCode metadata attribute.

Use values between 0 and 1 for relative quantities, which represent attribute values such as relativeHumidity, precipitationProbability, etc.

Use address attribute for civic locations as per schema.org
Use location attribute for geographical coordinates. Ideally use GeoJSON for codifying geospatial properties. That works from Orion 1.2 on. If not use, old NGSI version 1 type coords.

When an entity attribute is used as a link to other entities name it with the prefix ref plus the name of the target (linked) entity type. For instance refStreetlightModel, represents an attribute which contains a reference to an entity of type StreetlightModel.

Attribute type must be DateTime.
Use the date prefix for naming entity attributes representing dates (or complete timestamps). Ex. dateLastEmptying.
dateCreated must be used to denote the (digital) entity's creation date.
dateModified must be used to denote the (digital) entity's last update date.
dateCreated and dateModified are special entity attributes provided off-the-shelf by NGSIv2 implementations. Be careful because they can be different than the actual creation or update date of the real world entity represented by its corresponding digital entity.
When necessary define additional attributes to capture precisely all the details about dates. For instance, to denote the date at which a weather forecast was delivered an attribute named dateIssued can be used. In that particular case just reusing dateCreated would be incorrect because the latter would be the creation date of the (digital) entity representing the weather forecast which typically might have a delay.

Use a metadata attribute named timestamp for capturing the last update timestamp of a dynamic attribute. Please note that this is the actual date at which the measured value was obtained (from a sensor, by visual observation, etc.), and that date might be different than the date (metadata attribute named dateModified as per NGSIv2) at which the attribute of the digital entity was updated, as typically there might be delay, specially on IoT networks which deliver data only at specific timeslots.

In case of doubt check other existing models!