In Thing'in the labels are used to tag the entities (Avatar, Properties or Relationships). They add flexibility in the data definition when considering the regidity of the ontology concepts.
A label is a character string, and can be defined by users. Before use, a label should be registered to avoid the proliferation.
Label can not contain / character and can not begins with _ character. Some reserved properties can not be used as label property (even if the label property has been created) (e.g. domain, iri...). Other properties are automatically traduced in its ontologic version (e.g. description, type)
Currently, no restriction is put in place, but in a near future, we should consider restrictions at the RBAC level or the in the naming.
Endpoint : POST - /labels/
Payload :
{
"name": "string",
"description": "string",
"type": "string"
}
Where:
name is free, but shall be unique in the platform.description field gives the prefered usage of this label.type gives the label application type : instance (on avatar itself), property (as property on avatar or property relation), relationship (on relationship).Endpoint : GET - /labels/
Parameters :
name : a prefix of the labels to find.keywords : keywords separated with coma to find into the description.Endpoint : GET - /labels/{name}
Parameters :
name : the label name to retrieve.A label can be used at different level : at the avatar instance level to tag the avatar, at relationship level to tag the relation or to be used as a property name.
In the examples below, the following labels are used :
{
"name": "tag:red",
"description": "This is an example instance label, i.e. equivalent of a node type/class",
"type": "instance"
}
{
"name": "tag:prop1",
"description": "This is an example property label, i.e. equivalent of a node property/field",
"type": "property"
}
{
"name": "tag:prop2",
"description": "This is a second example property label, i.e. equivalent of a node property/field",
"type": "property"
}
{
"name": "tag:red",
"description": "This is an example relationship label, i.e. equivalent of a relationship(edge) type/class",
"type": "relationship"
}
The following Turtle example shows the different usages of labels. (this syntax to describe property and relation are defined in section Core Model.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix : <http://orange-labs.fr/fog/ont/iot.owl#> .
@prefix ngsi: <https://uri.etsi.org/ngsi-ld/> .
<http://www.example.com/obj1>
:label "tag:red"^^xsd:string ; << label to tag the avatar
:hasProperty [
:type "Integer"^^xsd:string ;
:label "tag:prop1"^^xsd:string ; << label as property name
ngsi:hasValue "10"^^xsd:string
] ;
:hasRelationship [
:label "tag:edge1"^^xsd:string ; << label to tag the relationship
ngsi:hasObject <http://www.example.com/obj2> ;
:hasProperty [
:label "tag:prop1"^^xsd:string ; << label as property name of a relationship
:type "Double"^^xsd:string ;
ngsi:hasValue "1978.011"^^xsd:string
] ;
:hasProperty [
:label "tag:prop2"^^xsd:string ;
:type "String"^^xsd:string ;
ngsi:hasValue "deuxieme"^^xsd:string
]
] .
Here the equivalent JSON payload:
{
"_iri": "http://www.example.com/toto",
"_labels": [
"tag:red"
],
"tag:prop1": 10,
"_outE": [
{
"_label": "tag:edge1",
"_targetIRI": "http://www.example.com/toto0",
"tag:prop2": "deuxieme",
"tag:prop1": 1978.011
}
]
}
An instance label, i.e. an avatar tag/class, is defined in the graph database as a vertex, such as from a label, it is possible to retrieve all the avatars belonging to this label through the graph. An index dedicated to avatar's labels is also declared, thus accessing avatars via their label(s) is efficient.
At edge level, the relationship labels are implemented as a value of a property (_labels).
When a property label is used, it is implemented directly as a property in the vertex.