Commit ba92c2a6 authored by Jason Fox's avatar Jason Fox
Browse files

Switch to examples.

Reference Annex B.
Clarify Scoped attribute names
parent 7ddfb241
Loading
Loading
Loading
Loading
Loading
+55 −30
Original line number Diff line number Diff line
@@ -199,35 +199,50 @@ Entity Type is to delete the Entity and re-create it with the same _`id`_.
Alternatively, a batch upsert with ["replace"]{.HTML-Code} update mode can be
used, as described in Clause+++clause-10+++10.3.3.
The following names shall be avoided when defining Entity Types, as definitions
already exist within the core _`@context`_, and are reserved for use as data
types within the NGSI-LD Core API itself:
- ["Attribute"]{.HTML-Code}, ["AttributeList"]{.HTML-Code} ,
  ["ContextSourceIdentity"]{.HTML-Code} ,
  ["ContextSourceNotification"]{.HTML-Code},
  ["ContextSourceRegistration"]{.HTML-Code}, ["EntityTypeInfo"]{.HTML-Code} ,
  ["EntityTypeList"]{.HTML-Code}, ["ExecutionResultDetails"]{.HTML-Code},
  ["GeoProperty"]{.HTML-Code} , ["JsonProperty"]{.HTML-Code},
  ["LanguageProperty"]{.HTML-Code}, ["ListProperty"]{.HTML-Code} ,
  ["ListRelationship"]{.HTML-Code}, ["Query"]{.HTML-Code},
  ["Notification"]{.HTML-Code}, ["Property"]{.HTML-Code},
  ["Relationship"]{.HTML-Code}, ["Snapshot"]{.HTML-Code},
  ["SnapshotNotification"]{.HTML-Code} , ["Subscription"]{.HTML-Code},
  ["TemporalProperty"]{.HTML-Code}, ["VocabProperty"]{.HTML-Code}
The following names are defined in the core _`@context`_ using their standard
GeoJSON-LD definitions [i.13], and reserved for use in geographic operations:
- ["Feature"]{.HTML-Code}, ["FeatureCollection"]{.HTML-Code},
  ["GeometryCollection"]{.HTML-Code}, ["LineString"]{.HTML-Code},
  ["MultiLineString"]{.HTML-Code}, ["MultiPoint"]{.HTML-Code} ,
  ["MultiPolygon"]{.HTML-Code}, ["Point"]{.HTML-Code}, ["Polygon"]{.HTML-Code}
Users should name and define Entity types relevant to their own data model in a
user _`@context`_. These term definitions should **avoid the use** of the terms
already defined within the core _`@context`_, as such terms are reserved to be
used as data types within the NGSI-LD Core API itself, and therefore cannot be
redefined elsewhere.
<!-- prettier-ignore-start -->
>>> [!tip] EXAMPLE 1:
["Attribute"]{.HTML-Code} , ["Notification"]{.HTML-Code},  ["Query"]{.HTML-Code}, ["Relationship"]{.HTML-Code}
>>>
<!-- prettier-ignore-end -->
GeoJSON-LD type definitions [i.13] are also defined in the core _`@context`_ and
reserved for use in geographic operations:
<!-- prettier-ignore-start -->
>>> [!tip] EXAMPLE 2:
["Feature"]{.HTML-Code} , ["FeatureCollection"]{.HTML-Code}, ["Point"]{.HTML-Code}, ["Polygon"]{.HTML-Code}
>>>
<!-- prettier-ignore-end -->
The following names are defined in the Core _`@context`_ and are reserved for
temporal definitions:
- ["Date"]{.HTML-Code}, ["DateTime"]{.HTML-Code}, ["Time"]{.HTML-Code}
<!-- prettier-ignore-start -->
>>> [!tip] EXAMPLE 3:
["Date"]{.HTML-Code} , ["DateTime"]{.HTML-Code}, ["Time"]{.HTML-Code}
>>>
<!-- prettier-ignore-end -->
A full list of terms defined for use by the NGSI-LD API can be discovered through
reading the Core NGSI-LD _`@context`_ found in Annex B.
### 5.2.4 Simple Attributes / temporal Attributes
@@ -326,11 +341,18 @@ to be a system attribute.
### 5.2.5 Matrix of all Attributes
Table+++below gives a list of all defined attribute names within NGSI-LD data
types. User-defined terms within the user _`@context`_ may reuse these terms
**as is**, but shall avoid amending the definition these attribute names, since
the Core _`@context`_ definition always has priority, and will override any
changes defined in the user _`@context`_.
Table+++below gives a list of all attribute names used within NGSI-LD data
types. The core _`@context`_ provides term definitions for all of these
attribute names. Where possible, users should avoid the repurposing of these
attribute names when creating their own user-defined term definitions in the
user _`@context`_.
Unscoped term definitions for attribute names within the core _`@context`_,
**can never be overridden**, since the core _`@context`_ definition always has
priority over any user _`@context`_ definition. Core _`@context`_ definitions
for attribute names which are defined as Property-scoped or Type-scoped (as
described by the JSON-LD specification [n.8], section 1.4) may be overridden
where necessary, although this usage is still discouraged.
<!-- prettier-ignore-start -->
@@ -789,6 +811,9 @@ Core _`@context`_:
- ["langString"]{.HTML-Code} is defined to retain its standard RDF datatype
  [n.7].
The full list of attribute names defined as terms can be discovered through reading
the Core NGSI-LD _`@context`_ found in Annex B.
### 5.2.6 Data types
#### 5.2.6.1 Introduction