Should we support JSON-LD?

[jmcanterafonseca]

JSON-LD is starting to turn into a widely accepted format for describing linking data. See for instance

https://developers.google.com/structured-data/events/venues

I think it would be nice that Orion supported this language both for context updates and for querying context.

[fgalan]

The idea would be the following, summarizing a discussion with @jmcanterafonseca and Sergio García:

• Orion will support application/json+ld MIME type in Accept for GET operations (or maybe in options, in the same way that text works, e.g. to get JSON-LD easily in a browser)
• When application/json+ld is used, the following document is generated (basically, the same that in a conventional NGSIv2 GET payload but with @ before id and type):

{
  "@id": "Room1",
  "@type": "Room"
  "temperature": 23,
  "pressure": 720,
  "colour": "red"
}

• The response will have a Link header in the following way:

Link: <URL_CTX>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

• URL_CTX is composed in the following way: prefix + entityType, where prefix is set by a CLI parameter at booting time, e.g. -jsonLdUrlPrefix (bad name, let's think a better one).
• URL_CTX point to a third system (outside Orion) that will generate the @context properly. That thrid system could use Orion to get an model entity (up to it).

[GillesPrivat]

We fully agree that JSON-LD should definitely get integrated into the next version of NGSI, and not only used by ORION. The optional use of, at least, @id, @type and @context is uncontroversial and can be taken up incrementally. it will have to be discussed whether to make the use @ids and full URIs base on an @context (instead of local names and types) mandatory (or at least strongly recommended) in this new version?

[marcc-orange]

@fgalan Does the URL_CTX proposition supposes that only one JSON-LD Context is shared among all the Context Entities known to Orion ? It feels strange to suppose this, as a single Orion instance could be used by several tenants working on multiples unrelated domains (hearth, smarticty) requiring multiple Context URLs.

Even if in the current APIv2, Context Registration is mainly about defining Context Producers (using the callbackproperty), we could maybe also use Context Registration to add JSON-LD Context to Context Entities.

In this case, entities defined by a Context Registration could have an additional context property along with id/idPattern and type properties. When such Context Entity is then retrieved (EDIT: with Accept header), it would then be formated with @id, @type and @context properties.

POST v2/registrations

        {
            "subject": {
                "entities": [
                    {
                        "type": "Room",
                        "context": "http://schema.org/"
                    }
                ],
                "attributes": [ "temperature", "pressure", "color" ]
            },
            "duration": "PT1M"
        }

GET /v2/entities/room1

{
  "@id": "Room1",
  "@type": "Room",
  "@context": "http://schema.org",
  "temperature": 23,
  "pressure": 720,
  "color": "red"
}

It is then the responsibility of the Context Producer to provide the correct JSON-LD Context associated to the Context Entities it publishes to Orion.

[GillesPrivat]

Backward compatibility of JSON-NGSIv1 with JSON-LD could be ensured in a very minimal way by aliasing the @id and @type JSON-LD keywords { "@context" { "id"="@id" "type"="@type" }

In the JSON-LD data model an NGSI entity is basically a JSON "node object" , restricted however to having only properties with value objects If we adopt the JSON-LD data model in NGSIV2, it is no longer necessary to define these properties as attributes, which adds an additional level of indirection. For backward compatibility, the levels of attributes and attribute domains could be kept but they would be ignored when parsing a legacy NGSI description to transform it in to JSON-LD , attaching the individual attributes directly to the entity as properties with the corresponding types taking an example form the Cepheus docs, this NGSI description { { "id": "Room31", // Room 1 on floor 3 (could be anything else) "type":"Room", // all sensors must use the same "Room" type "attributes": [ { "name":"temperature", "type":"double", "value":"21" }, // this is the value of the sensors { "name":"floor", "type":"string", "value":"3" } // the room is on the third foor ] }

could be interpreted directly as JSON-LD with a minimal @context as defined above,

but it could be replaced by this generic JSON-LD description by removing the "attribute" layer

{ "@id": "Room31", // this local identifier must be mapped to an IRI in an context "@type":"Room", // this node type must be defined in a domain specific @context

    { "temperature" : "21" }, // the temperature property must refer to a transversal  @context where it would be defined with an xsd numeric value type
    { "floor":"3" } // the floor property may be attached to the room node type and defined in a the same @context, with a string value type as its default 

}

What is much more important is the possibility to describe relationships between entities : this where we definitely have to go beyond the NGSIv1 data model which is entity-centric and strictly hierarchical, to adopt a graph model, basically the RDF model that underlies JSON-LD : in this model we can describe node to node relationships as properties, and not only node to value relationships

[fgalan]

This issue is not especifically related with NGISv2, so APIv2 label is removed. The issue keeps opened.

CC: @jmcanterafonseca