diff --git a/md/annex-a.md b/md/annex-a.md index 8bda05c5b408b6fd4d50379cfa194edcce27813d..6c1c980355127b8845ae1b7275b131e90ec4c5c3 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -24,11 +24,17 @@ This example illustrates how to create a new Entity of type ### A.2.2 HTTP request +#### A.2.2.1 Creation using a JSON-LD body and no Link header + **POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} -Content-Type: application/ld+json +**Request Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} + +- [Content-Length: 927]{.HTML-Code} -Content-Length: 927 +**Request Body** ```json { @@ -77,11 +83,83 @@ Content-Length: 927 } ``` +#### A.2.2.2 Creation using a JSON body and Link Header + +**POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} + +**Request Headers** + +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +- [Content-Type: application/**json**]{.HTML-Code} + +- [Content-Length: 783]{.HTML-Code} + + + +>>> [!note] NOTE: + +The URL found within the Link header above only refers to the user + _`@context`_ since the addition of the core _`@context`_ can be implied. + +>>> + + + +**Request Body** + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": { + "type": "Property", + "value": "Mercedes" + }, + "street": { + "type": "LanguageProperty", + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "type": "Relationship", + "objectType": "OffStreetParking", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "type": "VocabProperty", + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "type": "ListProperty", + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "type": "Relationship", + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + } +} +``` + ### A.2.3 HTTP response -201 Created +**Status Code:** 201 Created -Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567 +**Response Headers** + +- [Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567]{.HTML-Code} ## A.3 Query Entities @@ -102,19 +180,46 @@ NGSI-LD Simplified Format. ### A.3.2 HTTP request +#### A.3.2.1 Query requesting a JSON-LD Response + **GET** [/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} -Link: -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +#### A.3.2.2 Query requesting a JSON Response + +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} + +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.3.3 HTTP response -200 OK +#### A.3.3.1 JSON-LD Response + +The JSON-LD response contains a JSON-LD body with _`@context`_ and returns no +Link Header. + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -130,6 +235,59 @@ Content-Type: application/ld+json ] ``` +#### A.3.3.2 JSON Response + +The JSON only response contains a Link Header and returns a JSON body without an +_`@context`_. + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**json**]{.HTML-Code} +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "brandName": "Volvo" + } +] +``` + + + +>>> [!note] NOTE: + +The [Context Broker]{.HTML-Keyboard} endpoint _`/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9`_ +returns the following JSON-LD _`@context`_ referencing two files: + +```json +{ + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + + +This ensures that the response contains **only one HTTP Link +header** with the link relationship +["http://www.w3.org/ns/json-ld#context"]{.HTML-Code} +and therefore fully complies with the JSON-LD Specification [n.8] + +>>> + + + ## A.4 Query Entities (pagination) ### A.4.1 Introduction @@ -151,20 +309,27 @@ Simplified Format. Limit the number of entities retrieved to 2. **GET** [/ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Accept: application/**ld+json**]{.HTML-Code} + +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.4.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** -Content-Type: application/ld+json +- [Content-Type: application/**ld+json**]{.HTML-Code} -Link: -</ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=2>; -rel="next"; type="application/ld+json" +- [Link: + </ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=>; + rel="next"; type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json [ @@ -226,16 +391,24 @@ _`brandName`_ attribute is omitted in the response. **GET** [/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.5.3 HTTP response #1 -200 OK +**Status Code:** 200 OK -Content-Type: application/ld+json +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} + +**Response Body** ```json [ @@ -272,16 +445,24 @@ Content-Type: application/ld+json **GET** [/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.5.5 HTTP response #2 -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -336,16 +517,24 @@ required. **GET** [/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=**temporalValues**]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Accept: application/**ld+json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.6.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -387,19 +576,29 @@ the NGSI-LD system. **GET** [/ngsi-ld/v1/types]{.HTML-Variable} -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.7.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** -Content-Type: application/json +- [Content-Type: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json { @@ -444,19 +643,29 @@ currently available in the NGSI-LD system. **GET** [/ngsi-ld/v1/types?details=true]{.HTML-Variable} -Accept: application/json +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.8.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** -Content-Type: application/json +- [Content-Type: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json [ @@ -520,19 +729,29 @@ instances are currently available in the NGSI-LD system). [Alternative with FQN: **GET** [/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]{.HTML-Variable} -Accept: application/json +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.9.3 HTTP response -200 OK +**Status Code:** 200 OK -Content-Type: application/json +**Response Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json { @@ -588,19 +807,29 @@ in the NGSI-LD system that have an attribute with the respective name. **GET** [/ngsi-ld/v1/attributes]{.HTML-Variable} -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.10.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** -Content-Type: application/json +- [Content-Type: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json { @@ -648,19 +877,29 @@ attribute name belongs. **GET** [/ngsi-ld/v1/attributes?details=true]{.HTML-Variable} -Accept: application/json +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.11.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** -Content-Type: application/json +- [Content-Type: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json [ @@ -737,19 +976,29 @@ the NGSI-LD system). [/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]{.HTML-Variable} \] -Accept: application/json +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.12.3 HTTP response -200 OK +**Status Code:** 200 OK -Content-Type: application/json +**Response Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json { @@ -786,16 +1035,24 @@ strings in German. [/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]=="Vauxhall Viva"&format=**simplified**&lang=de]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.13.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -833,16 +1090,24 @@ Give back the maximum and average _`speed`_ of Entities of type **GET** [/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=**aggregatedValues**]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Accept: application/**ld+json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.14.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -888,16 +1153,24 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. **GET** [/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Accept: application/**ld+json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.15.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** -Content-Type: application/ld+json +- [Content-Type: application/**ld+json**]{.HTML-Code} + +**Response Body** ```json [ @@ -1002,16 +1275,24 @@ been set before, e.g. on 1st of August 2018 at 11 AM. **GET** [/ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ="/Madrid/Centro"]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.16.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ diff --git a/md/clause-10.md b/md/clause-10.md index db0bba5253245408d30df3338654659ee82ca34f..1c1786ad2ce525c414cb4be1a73f29aaf0923317 100644 --- a/md/clause-10.md +++ b/md/clause-10.md @@ -214,6 +214,10 @@ Table: Serve \@contexts URL parameters +-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ | Name | Data Type | Cardinality | Remarks | +=================+=================+=================+======================================================================================+ +| core | String | 0..1 | A semantically versioned string in the form *major.minor*, which conforms to a | +| | | | version of the NGSI-LD specification. When present the endpoint returns an array | +| | | | consisting of the user _`@context`_ URL and the core _`@context`_ URL. | ++-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ | details | Boolean | 0..1 | Whether the content of the _`@context`_ or its metadata is requested. | +-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ ::: @@ -240,9 +244,11 @@ Table: Serve \@context request body and possible responses | | | | | | | Response Body | Data Type | Cardinality | Response Codes | Remarks | | +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | | | | If the parameter details are _`false`_ or missing, response body contains a JSON object that has a root node named _`@context`_, which represents a JSON-LD "local context". | +| | | | | If the parameter _`details`_ is _`false`_ or missing, response body contains a JSON object that has a root node named _`@context`_, which represents a JSON-LD "local context". | +| | | | | | +| | JSON Object | 1 | 200 OK | If the parameter _`core`_ is present response body contains a JSON object that has a root node named _`@context`_ holding an array of URLs matching to JSON-LD "local context" and core context. | | | | | | | -| | JSON Object | 1 | 200 OK | If the parameter details are _`true`_, response body contains a JSON object as defined in [n.1] ~clause 13.4.5, which metadata of a JSON-LD "local context". | +| | | | | If the parameter _`details`_ is _`true`_, response body contains a JSON object as defined in [n.1] ~clause 13.4.5, which metadata of a JSON-LD "local context". The _`core`_ if present is ignored. | | +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | | | | It is used to indicate that the request or its content is incorrect, see clause 6.3.2. | | | | | | | diff --git a/md/clause-6.md b/md/clause-6.md index e5dbf6e9c43239cd74931914b988c2591600ce25..b6172e13777a96729479d41a348c733e289fb1d0 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -151,6 +151,9 @@ this header (marking it as a link to a JSON-LD _`@context`_ ). The third and final parameter flags the MIME type of the linked resource (JSON-LD). + +[Link: <​http://json-ld.org/contexts/person.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} + >>>