Data models guidelines
This is a set of guidelines for defining new data models.
- Use English terms, preferably American English.
- Use camel case syntax for attribute names (
- Entity type names must start with a Capital letter, for instance,
- Use names and not verbs for attribute names, ex.
name, qualifying it when necessary, ex.
- Avoid plurals in attribute names, but state clearly when a list of items fits. Ex.
- 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 (
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
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
1for relative quantities, which represent attribute values such as
addressattribute for civic locations as per schema.org
locationattribute 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
Modelling linked data
- When an entity attribute is used as a link to other entities name
it with the prefix
refplus the name of the target (linked) entity type. For instance
refStreetlightModel, represents an attribute which contains a reference to an entity of type
Attribute type must be
dateprefix for naming entity attributes representing dates (or complete timestamps). Ex.
dateCreatedmust be used to denote the (digital) entity's creation date.
dateModifiedmust be used to denote the (digital) entity's last update date.
dateModifiedare 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
dateIssuedcan be used. In that particular case just reusing
dateCreatedwould 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
timestampfor 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
dateModifiedas 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.
Some of the most used attributes
In case of doubt check other existing models!