From 8e3f36b4ce4088aaaca0b7871e710c45bdab8d6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Gonz=C3=A1lez-S=C3=A1nchez?= <55086789+daniel-gonzalez-sanchez@users.noreply.github.com> Date: Thu, 14 Mar 2024 00:33:53 +0100 Subject: [PATCH 001/112] Initial commit --- README.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8ac934e --- /dev/null +++ b/README.md @@ -0,0 +1,2 @@ +# ngsi-ld-oas +OpenAPI Specification for NGSI-LD API -- GitLab From e100fce0e5b24565d2a6d46ad8b094eecef18908 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 14 Mar 2024 01:03:34 +0100 Subject: [PATCH 002/112] Create an initial fork repository to work on the OpenAPI Specification (OAS) for the NGSI-LD API specified by the cross-cutting Context Information Management (CIM) ETSI Industry Specification Group (ISG). --- LICENSE | 23 + README.md | 36 +- coreContext/ngsi-ld-core-context-v1.3.jsonld | 221 + coreContext/ngsi-ld-core-context-v1.4.jsonld | 253 + coreContext/ngsi-ld-core-context-v1.5.jsonld | 264 + coreContext/ngsi-ld-core-context-v1.6.jsonld | 299 + examples/@context_C.2.4.json | 42 + examples/AttributeList_C.5.10.3.json | 11 + examples/Attribute_C.5.12.3.json | 8 + examples/Attributes_details_C.5.11.3.json | 36 + examples/ContextSourceRegistration_C.3.json | 52 + examples/EntityList_C.5.4.3.json | 20 + examples/EntityTemporal_C.5.5.3.json | 27 + .../EntityTemporal_simplified_C.5.6.3.json | 18 + examples/EntityTypeInfo_C.5.9.3.json | 32 + examples/EntityTypeList_C.5.7.json | 9 + examples/EntityType_C.5.8.3.json | 25 + examples/Entity_lang_C.5.13.3.json | 11 + examples/FeatureCollection_concise_C.2.3.json | 59 + .../FeatureCollection_normalized_C.2.3.json | 87 + .../FeatureCollection_simplified_C.2.3.json | 45 + examples/Feature_concise_C.2.3.json | 29 + examples/Feautre_keyValues_C.2.3.json | 22 + examples/Feautre_normalized_C.2.3.json | 43 + examples/OffStreetParking_concise_C.2.3.json | 22 + .../OffStreetParking_normalized_C.2.3.json | 36 + .../OffStreetParking_simplified_C.2.3.json | 15 + examples/Subscription_C.4.json | 28 + examples/Vehicle_MultiAttribute_C.2.2.json | 32 + examples/Vehicle_concise_C.2.2.json | 24 + examples/Vehicle_concise_lang_C.2.2.json | 22 + examples/Vehicle_datetime_C.6.json | 15 + examples/Vehicle_keyValues_C.2.2.json | 16 + examples/Vehicle_keyValues_lang_C.2.2.json | 13 + examples/Vehicle_normalized_C.2.2.json | 30 + examples/Vehicle_normalized_lang_C.2.2.json | 28 + examples/Vehicle_scope_C.5.15.3.json | 76 + .../Vehicle_temporal_aggregated_C.5.14.3.json | 21 + examples/Vehicle_temporal_scope_C.5.16.3.json | 44 + ngsi-ld-api.yaml | 5236 +++++++++++++++++ 40 files changed, 7328 insertions(+), 2 deletions(-) create mode 100644 LICENSE create mode 100644 coreContext/ngsi-ld-core-context-v1.3.jsonld create mode 100644 coreContext/ngsi-ld-core-context-v1.4.jsonld create mode 100644 coreContext/ngsi-ld-core-context-v1.5.jsonld create mode 100644 coreContext/ngsi-ld-core-context-v1.6.jsonld create mode 100644 examples/@context_C.2.4.json create mode 100644 examples/AttributeList_C.5.10.3.json create mode 100644 examples/Attribute_C.5.12.3.json create mode 100644 examples/Attributes_details_C.5.11.3.json create mode 100644 examples/ContextSourceRegistration_C.3.json create mode 100644 examples/EntityList_C.5.4.3.json create mode 100644 examples/EntityTemporal_C.5.5.3.json create mode 100644 examples/EntityTemporal_simplified_C.5.6.3.json create mode 100644 examples/EntityTypeInfo_C.5.9.3.json create mode 100644 examples/EntityTypeList_C.5.7.json create mode 100644 examples/EntityType_C.5.8.3.json create mode 100644 examples/Entity_lang_C.5.13.3.json create mode 100644 examples/FeatureCollection_concise_C.2.3.json create mode 100644 examples/FeatureCollection_normalized_C.2.3.json create mode 100644 examples/FeatureCollection_simplified_C.2.3.json create mode 100644 examples/Feature_concise_C.2.3.json create mode 100644 examples/Feautre_keyValues_C.2.3.json create mode 100644 examples/Feautre_normalized_C.2.3.json create mode 100644 examples/OffStreetParking_concise_C.2.3.json create mode 100644 examples/OffStreetParking_normalized_C.2.3.json create mode 100644 examples/OffStreetParking_simplified_C.2.3.json create mode 100644 examples/Subscription_C.4.json create mode 100644 examples/Vehicle_MultiAttribute_C.2.2.json create mode 100644 examples/Vehicle_concise_C.2.2.json create mode 100644 examples/Vehicle_concise_lang_C.2.2.json create mode 100644 examples/Vehicle_datetime_C.6.json create mode 100644 examples/Vehicle_keyValues_C.2.2.json create mode 100644 examples/Vehicle_keyValues_lang_C.2.2.json create mode 100644 examples/Vehicle_normalized_C.2.2.json create mode 100644 examples/Vehicle_normalized_lang_C.2.2.json create mode 100644 examples/Vehicle_scope_C.5.15.3.json create mode 100644 examples/Vehicle_temporal_aggregated_C.5.14.3.json create mode 100644 examples/Vehicle_temporal_scope_C.5.16.3.json create mode 100644 ngsi-ld-api.yaml diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4436d6d --- /dev/null +++ b/LICENSE @@ -0,0 +1,23 @@ +Copyright 2019 ETSI + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. +3. Neither the name of the copyright holder nor the names of its contributors + may be used to endorse or promote products derived from this software without + specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file diff --git a/README.md b/README.md index 8ac934e..f1e138c 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,34 @@ -# ngsi-ld-oas -OpenAPI Specification for NGSI-LD API +# NGSI-LD OAS + +This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API specified by the cross-cutting Context Information Management (CIM) ETSI Industry Specification Group (ISG). + +> **IMPORTANT NOTE:** +> +> This is a fork of the original OpenAPI Specification for the NGSI-LD API, which is available on the ETSI Forge [here](https://forge.etsi.org/rep/cim/NGSI-LD). + +## Online Documentation + +### Specification Document + +* [ETSI GS CIM 009](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.06.01_60/gs_CIM009v010601p.pdf) + +### Navigate API + +* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) +* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) + +## Developers + +Please note that the OpenAPI specification for the NGSI-LD API is provided as a single file. The reason behind this design choice is to leverage OpenAPI extensions supported by IDEs like VS Code, which are not compatible with multi-file OpenAPI specifications. + +The NGSI-LD API specification has been developed using VS Code supported by the [OpenAPI Swagger Editor Extension in VS Code](https://42crunch.com/tutorial-openapi-swagger-extension-vs-code/). We highly recommend using this extension when developing. + +## Additional resources + +The repository includes the following resources that may be useful when using the NGSI-LD API: +- [Core JSON-LD @context](./coreContext/): This folder contains JSON-LD core @context defined by the NGSI-LD API. For convencience, the folder includes @context files for different versions of the API. +- [NGSI-LD payload examples](./examples/): Includes examples of NGSI-LD payloads for multiple types of NGSI-LD operations. These examples can also be found in the Annex sections of the ETSI ISG CIM 009 document. + +## License + +The content of this repository and the files contained are released under the BSD-3-Clause license. See the attached LICENSE file or visit https://forge.etsi.org/legal-matters. diff --git a/coreContext/ngsi-ld-core-context-v1.3.jsonld b/coreContext/ngsi-ld-core-context-v1.3.jsonld new file mode 100644 index 0000000..06518f9 --- /dev/null +++ b/coreContext/ngsi-ld-core-context-v1.3.jsonld @@ -0,0 +1,221 @@ +{ + "@context": { + "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", + "geojson": "https://purl.org/geojson/vocab#", + "id": "@id", + "type": "@type", + "Attribute": "ngsi-ld:Attribute", + "AttributeList": "ngsi-ld:AttributeList", + "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", + "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", + "Date": "ngsi-ld:Date", + "DateTime": "ngsi-ld:DateTime", + "EntityType": "ngsi-ld:EntityType", + "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", + "EntityTypeList": "ngsi-ld:EntityTypeList", + "Feature": "geojson:Feature", + "FeatureCollection": "geojson:FeatureCollection", + "GeoProperty": "ngsi-ld:GeoProperty", + "GeometryCollection": "geojson:GeometryCollection", + "LineString": "geojson:LineString", + "MultiLineString": "geojson:MultiLineString", + "MultiPoint": "geojson:MultiPoint", + "MultiPolygon": "geojson:MultiPolygon", + "Notification": "ngsi-ld:Notification", + "Point": "geojson:Point", + "Polygon": "geojson:Polygon", + "Property": "ngsi-ld:Property", + "Relationship": "ngsi-ld:Relationship", + "Subscription": "ngsi-ld:Subscription", + "TemporalProperty": "ngsi-ld:TemporalProperty", + "Time": "ngsi-ld:Time", + "accept": "ngsi-ld:accept", + "attributeCount": "ngsi-ld:attributeCount", + "attributeDetails": "ngsi-ld:attributeDetails", + "attributeList": { + "@id": "ngsi-ld:attributeList", + "@type": "@vocab" + }, + "attributeName": { + "@id": "ngsi-ld:attributeName", + "@type": "@vocab" + }, + "attributeNames": { + "@id": "ngsi-ld:attributeNames", + "@type": "@vocab" + }, + "attributeTypes": { + "@id": "ngsi-ld:attributeTypes", + "@type": "@vocab" + }, + "attributes": { + "@id": "ngsi-ld:attributes", + "@type": "@vocab" + }, + "attrs": "ngsi-ld:attrs", + "bbox": { + "@container": "@list", + "@id": "geojson:bbox" + }, + "coordinates": { + "@container": "@list", + "@id": "geojson:coordinates" + }, + "createdAt": { + "@id": "ngsi-ld:createdAt", + "@type": "DateTime" + }, + "csf": "ngsi-ld:csf", + "data": "ngsi-ld:data", + "datasetId": { + "@id": "ngsi-ld:datasetId", + "@type": "@id" + }, + "description": "http://purl.org/dc/terms/description", + "detail": "ngsi-ld:detail", + "endAt": { + "@id": "ngsi-ld:endAt", + "@type": "DateTime" + }, + "endTimeAt": { + "@id": "ngsi-ld:endTimeAt", + "@type": "DateTime" + }, + "endpoint": "ngsi-ld:endpoint", + "entities": "ngsi-ld:entities", + "entityCount": "ngsi-ld:entityCount", + "entityId": { + "@id": "ngsi-ld:entityId", + "@type": "@id" + }, + "error": "ngsi-ld:error", + "errors": "ngsi-ld:errors", + "expiresAt": { + "@id": "ngsi-ld:expiresAt", + "@type": "DateTime" + }, + "features": { + "@container": "@set", + "@id": "geojson:features" + }, + "format": "ngsi-ld:format", + "geoQ": "ngsi-ld:geoQ", + "geometry": "geojson:geometry", + "geoproperty": "ngsi-ld:geoproperty", + "georel": "ngsi-ld:georel", + "idPattern": "ngsi-ld:idPattern", + "information": "ngsi-ld:information", + "instanceId": { + "@id": "ngsi-ld:instanceId", + "@type": "@id" + }, + "isActive": "ngsi-ld:isActive", + "lastFailure": { + "@id": "ngsi-ld:lastFailure", + "@type": "DateTime" + }, + "lastNotification": { + "@id": "ngsi-ld:lastNotification", + "@type": "DateTime" + }, + "lastSuccess": { + "@id": "ngsi-ld:lastSuccess", + "@type": "DateTime" + }, + "location": "ngsi-ld:location", + "managementInterval": "ngsi-ld:managementInterval", + "modifiedAt": { + "@id": "ngsi-ld:modifiedAt", + "@type": "DateTime" + }, + "notification": "ngsi-ld:notification", + "notifiedAt": { + "@id": "ngsi-ld:notifiedAt", + "@type": "DateTime" + }, + "object": { + "@id": "ngsi-ld:hasObject", + "@type": "@id" + }, + "objects": { + "@id": "ngsi-ld:hasObjects", + "@type": "@id", + "@container": "@list" + }, + "observationInterval": "ngsi-ld:observationInterval", + "observationSpace": "ngsi-ld:observationSpace", + "observedAt": { + "@id": "ngsi-ld:observedAt", + "@type": "DateTime" + }, + "operationSpace": "ngsi-ld:operationSpace", + "properties": "geojson:properties", + "propertyNames": { + "@id": "ngsi-ld:propertyNames", + "@type": "@vocab" + }, + "q": "ngsi-ld:q", + "reason": "ngsi-ld:reason", + "registrationName": "ngsi-ld:registrationName", + "relationshipNames": { + "@id": "ngsi-ld:relationshipNames", + "@type": "@vocab" + }, + "startAt": { + "@id": "ngsi-ld:startAt", + "@type": "DateTime" + }, + "status": "ngsi-ld:status", + "subscriptionId": { + "@id": "ngsi-ld:subscriptionId", + "@type": "@id" + }, + "subscriptionName": "ngsi-ld:subscriptionName", + "success": { + "@id": "ngsi-ld:success", + "@type": "@id" + }, + "temporalQ": "ngsi-ld:temporalQ", + "tenant": { + "@id": "ngsi-ld:tenant", + "@type": "@id" + }, + "throttling": "ngsi-ld:throttling", + "timeAt": { + "@id": "ngsi-ld:timeAt", + "@type": "DateTime" + }, + "timeInterval": "ngsi-ld:timeInterval", + "timeproperty": "ngsi-ld:timeproperty", + "timerel": "ngsi-ld:timerel", + "timesSent": "ngsi-ld:timesSent", + "title": "http://purl.org/dc/terms/title", + "triggerReason": "ngsi-ld:triggerReason", + "typeList": { + "@id": "ngsi-ld:typeList", + "@type": "@vocab" + }, + "typeName": { + "@id": "ngsi-ld:typeName", + "@type": "@vocab" + }, + "typeNames": { + "@id": "ngsi-ld:typeNames", + "@type": "@vocab" + }, + "unchanged": "ngsi-ld:unchanged", + "unitCode": "ngsi-ld:unitCode", + "updated": "ngsi-ld:updated", + "uri": "ngsi-ld:uri", + "value": "ngsi-ld:hasValue", + "values": { + "@id": "ngsi-ld:hasValues", + "@container": "@list" + }, + "watchedAttributes": { + "@id": "ngsi-ld:watchedAttributes", + "@type": "@vocab" + }, + "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" + } +} \ No newline at end of file diff --git a/coreContext/ngsi-ld-core-context-v1.4.jsonld b/coreContext/ngsi-ld-core-context-v1.4.jsonld new file mode 100644 index 0000000..45e3d6c --- /dev/null +++ b/coreContext/ngsi-ld-core-context-v1.4.jsonld @@ -0,0 +1,253 @@ +{ + "@context": { + "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", + "geojson": "https://purl.org/geojson/vocab#", + "id": "@id", + "type": "@type", + "Attribute": "ngsi-ld:Attribute", + "AttributeList": "ngsi-ld:AttributeList", + "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", + "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", + "Date": "ngsi-ld:Date", + "DateTime": "ngsi-ld:DateTime", + "EntityType": "ngsi-ld:EntityType", + "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", + "EntityTypeList": "ngsi-ld:EntityTypeList", + "Feature": "geojson:Feature", + "FeatureCollection": "geojson:FeatureCollection", + "GeoProperty": "ngsi-ld:GeoProperty", + "GeometryCollection": "geojson:GeometryCollection", + "LineString": "geojson:LineString", + "MultiLineString": "geojson:MultiLineString", + "MultiPoint": "geojson:MultiPoint", + "MultiPolygon": "geojson:MultiPolygon", + "Notification": "ngsi-ld:Notification", + "Point": "geojson:Point", + "Polygon": "geojson:Polygon", + "Property": "ngsi-ld:Property", + "Relationship": "ngsi-ld:Relationship", + "Subscription": "ngsi-ld:Subscription", + "TemporalProperty": "ngsi-ld:TemporalProperty", + "Time": "ngsi-ld:Time", + "accept": "ngsi-ld:accept", + "attributeCount": "ngsi-ld:attributeCount", + "attributeDetails": "ngsi-ld:attributeDetails", + "attributeList": { + "@id": "ngsi-ld:attributeList", + "@type": "@vocab" + }, + "attributeName": { + "@id": "ngsi-ld:attributeName", + "@type": "@vocab" + }, + "attributeNames": { + "@id": "ngsi-ld:attributeNames", + "@type": "@vocab" + }, + "attributeTypes": { + "@id": "ngsi-ld:attributeTypes", + "@type": "@vocab" + }, + "attributes": { + "@id": "ngsi-ld:attributes", + "@type": "@vocab" + }, + "attrs": "ngsi-ld:attrs", + "avg": { + "@id": "ngsi-ld:avg", + "@container": "@list" + }, + "bbox": { + "@container": "@list", + "@id": "geojson:bbox" + }, + "coordinates": { + "@container": "@list", + "@id": "geojson:coordinates" + }, + "createdAt": { + "@id": "ngsi-ld:createdAt", + "@type": "DateTime" + }, + "csf": "ngsi-ld:csf", + "data": "ngsi-ld:data", + "datasetId": { + "@id": "ngsi-ld:datasetId", + "@type": "@id" + }, + "description": "http://purl.org/dc/terms/description", + "detail": "ngsi-ld:detail", + "distinctCount": { + "@id": "ngsi-ld:distinctCount", + "@container": "@list" + }, + "endAt": { + "@id": "ngsi-ld:endAt", + "@type": "DateTime" + }, + "endTimeAt": { + "@id": "ngsi-ld:endTimeAt", + "@type": "DateTime" + }, + "endpoint": "ngsi-ld:endpoint", + "entities": "ngsi-ld:entities", + "entityCount": "ngsi-ld:entityCount", + "entityId": { + "@id": "ngsi-ld:entityId", + "@type": "@id" + }, + "error": "ngsi-ld:error", + "errors": "ngsi-ld:errors", + "expiresAt": { + "@id": "ngsi-ld:expiresAt", + "@type": "DateTime" + }, + "features": { + "@container": "@set", + "@id": "geojson:features" + }, + "format": "ngsi-ld:format", + "geoQ": "ngsi-ld:geoQ", + "geometry": "geojson:geometry", + "geoproperty": "ngsi-ld:geoproperty", + "georel": "ngsi-ld:georel", + "idPattern": "ngsi-ld:idPattern", + "information": "ngsi-ld:information", + "instanceId": { + "@id": "ngsi-ld:instanceId", + "@type": "@id" + }, + "isActive": "ngsi-ld:isActive", + "lastFailure": { + "@id": "ngsi-ld:lastFailure", + "@type": "DateTime" + }, + "lastNotification": { + "@id": "ngsi-ld:lastNotification", + "@type": "DateTime" + }, + "lastSuccess": { + "@id": "ngsi-ld:lastSuccess", + "@type": "DateTime" + }, + "location": "ngsi-ld:location", + "managementInterval": "ngsi-ld:managementInterval", + "max": { + "@id": "ngsi-ld:max", + "@container": "@list" + }, + "min": { + "@id": "ngsi-ld:min", + "@container": "@list" + }, + "modifiedAt": { + "@id": "ngsi-ld:modifiedAt", + "@type": "DateTime" + }, + "notification": "ngsi-ld:notification", + "notifiedAt": { + "@id": "ngsi-ld:notifiedAt", + "@type": "DateTime" + }, + "object": { + "@id": "ngsi-ld:hasObject", + "@type": "@id" + }, + "objects": { + "@id": "ngsi-ld:hasObjects", + "@type": "@id", + "@container": "@list" + }, + "observationInterval": "ngsi-ld:observationInterval", + "observationSpace": "ngsi-ld:observationSpace", + "observedAt": { + "@id": "ngsi-ld:observedAt", + "@type": "DateTime" + }, + "operationSpace": "ngsi-ld:operationSpace", + "properties": "geojson:properties", + "propertyNames": { + "@id": "ngsi-ld:propertyNames", + "@type": "@vocab" + }, + "q": "ngsi-ld:q", + "reason": "ngsi-ld:reason", + "registrationName": "ngsi-ld:registrationName", + "relationshipNames": { + "@id": "ngsi-ld:relationshipNames", + "@type": "@vocab" + }, + "startAt": { + "@id": "ngsi-ld:startAt", + "@type": "DateTime" + }, + "status": "ngsi-ld:status", + "stddev": { + "@id": "ngsi-ld:stddev", + "@container": "@list" + }, + "subscriptionId": { + "@id": "ngsi-ld:subscriptionId", + "@type": "@id" + }, + "subscriptionName": "ngsi-ld:subscriptionName", + "success": { + "@id": "ngsi-ld:success", + "@type": "@id" + }, + "sum": { + "@id": "ngsi-ld:sum", + "@container": "@list" + }, + "sumsq": { + "@id": "ngsi-ld:sumsq", + "@container": "@list" + }, + "totalCount": { + "@id": "ngsi-ld:totalCount", + "@container": "@list" + }, + "temporalQ": "ngsi-ld:temporalQ", + "tenant": { + "@id": "ngsi-ld:tenant", + "@type": "@id" + }, + "throttling": "ngsi-ld:throttling", + "timeAt": { + "@id": "ngsi-ld:timeAt", + "@type": "DateTime" + }, + "timeInterval": "ngsi-ld:timeInterval", + "timeproperty": "ngsi-ld:timeproperty", + "timerel": "ngsi-ld:timerel", + "timesSent": "ngsi-ld:timesSent", + "title": "http://purl.org/dc/terms/title", + "triggerReason": "ngsi-ld:triggerReason", + "typeList": { + "@id": "ngsi-ld:typeList", + "@type": "@vocab" + }, + "typeName": { + "@id": "ngsi-ld:typeName", + "@type": "@vocab" + }, + "typeNames": { + "@id": "ngsi-ld:typeNames", + "@type": "@vocab" + }, + "unchanged": "ngsi-ld:unchanged", + "unitCode": "ngsi-ld:unitCode", + "updated": "ngsi-ld:updated", + "uri": "ngsi-ld:uri", + "value": "ngsi-ld:hasValue", + "values": { + "@id": "ngsi-ld:hasValues", + "@container": "@list" + }, + "watchedAttributes": { + "@id": "ngsi-ld:watchedAttributes", + "@type": "@vocab" + }, + "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" + } +} \ No newline at end of file diff --git a/coreContext/ngsi-ld-core-context-v1.5.jsonld b/coreContext/ngsi-ld-core-context-v1.5.jsonld new file mode 100644 index 0000000..7d5b898 --- /dev/null +++ b/coreContext/ngsi-ld-core-context-v1.5.jsonld @@ -0,0 +1,264 @@ +{ + "@context": { + + "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", + "geojson": "https://purl.org/geojson/vocab#", + "id": "@id", + "type": "@type", + + "Attribute": "ngsi-ld:Attribute", + "AttributeList": "ngsi-ld:AttributeList", + "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", + "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", + "Date": "ngsi-ld:Date", + "DateTime": "ngsi-ld:DateTime", + "EntityType": "ngsi-ld:EntityType", + "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", + "EntityTypeList": "ngsi-ld:EntityTypeList", + "Feature": "geojson:Feature", + "FeatureCollection": "geojson:FeatureCollection", + "GeoProperty": "ngsi-ld:GeoProperty", + "GeometryCollection": "geojson:GeometryCollection", + "LineString": "geojson:LineString", + "LanguageProperty": "ngsi-ld:LanguageProperty", + "MultiLineString": "geojson:MultiLineString", + "MultiPoint": "geojson:MultiPoint", + "MultiPolygon": "geojson:MultiPolygon", + "Notification": "ngsi-ld:Notification", + "Point": "geojson:Point", + "Polygon": "geojson:Polygon", + "Property": "ngsi-ld:Property", + "Relationship": "ngsi-ld:Relationship", + "Subscription": "ngsi-ld:Subscription", + "TemporalProperty": "ngsi-ld:TemporalProperty", + "Time": "ngsi-ld:Time", + + "accept": "ngsi-ld:accept", + "attributeCount": "ngsi-ld:attributeCount", + "attributeDetails": "ngsi-ld:attributeDetails", + "attributeList": { + "@id": "ngsi-ld:attributeList", + "@type": "@vocab" + }, + "attributeName": { + "@id": "ngsi-ld:attributeName", + "@type": "@vocab" + }, + "attributeNames": { + "@id": "ngsi-ld:attributeNames", + "@type": "@vocab" + }, + "attributeTypes": { + "@id": "ngsi-ld:attributeTypes", + "@type": "@vocab" + }, + "attributes": { + "@id": "ngsi-ld:attributes", + "@type": "@vocab" + }, + "attrs": "ngsi-ld:attrs", + "avg": { + "@id": "ngsi-ld:avg", + "@container": "@list" + }, + "bbox": { + "@container": "@list", + "@id": "geojson:bbox" + }, + "coordinates": { + "@container": "@list", + "@id": "geojson:coordinates" + }, + "createdAt": { + "@id": "ngsi-ld:createdAt", + "@type": "DateTime" + }, + "csf": "ngsi-ld:csf", + "data": "ngsi-ld:data", + "datasetId": { + "@id": "ngsi-ld:datasetId", + "@type": "@id" + }, + "description": "http://purl.org/dc/terms/description", + "detail": "ngsi-ld:detail", + "distinctCount": { + "@id": "ngsi-ld:distinctCount", + "@container": "@list" + }, + "endAt": { + "@id": "ngsi-ld:endAt", + "@type": "DateTime" + }, + "endTimeAt": { + "@id": "ngsi-ld:endTimeAt", + "@type": "DateTime" + }, + "endpoint": "ngsi-ld:endpoint", + "entities": "ngsi-ld:entities", + "entityCount": "ngsi-ld:entityCount", + "entityId": { + "@id": "ngsi-ld:entityId", + "@type": "@id" + }, + "error": "ngsi-ld:error", + "errors": "ngsi-ld:errors", + "expiresAt": { + "@id": "ngsi-ld:expiresAt", + "@type": "DateTime" + }, + "features": { + "@container": "@set", + "@id": "geojson:features" + }, + "format": "ngsi-ld:format", + "geoQ": "ngsi-ld:geoQ", + "geometry": "geojson:geometry", + "geoproperty": "ngsi-ld:geoproperty", + "georel": "ngsi-ld:georel", + "idPattern": "ngsi-ld:idPattern", + "information": "ngsi-ld:information", + "instanceId": { + "@id": "ngsi-ld:instanceId", + "@type": "@id" + }, + "isActive": "ngsi-ld:isActive", + "lang": "ngsi-ld:lang", + "languageMap": { + "@id": "ngsi-ld:hasLanguageMap", + "@container": "@language" + }, + "lastFailure": { + "@id": "ngsi-ld:lastFailure", + "@type": "DateTime" + }, + "lastNotification": { + "@id": "ngsi-ld:lastNotification", + "@type": "DateTime" + }, + "lastSuccess": { + "@id": "ngsi-ld:lastSuccess", + "@type": "DateTime" + }, + "location": "ngsi-ld:location", + "managementInterval": "ngsi-ld:managementInterval", + "max": { + "@id": "ngsi-ld:max", + "@container": "@list" + }, + "min": { + "@id": "ngsi-ld:min", + "@container": "@list" + }, + "modifiedAt": { + "@id": "ngsi-ld:modifiedAt", + "@type": "DateTime" + }, + "notification": "ngsi-ld:notification", + "notifiedAt": { + "@id": "ngsi-ld:notifiedAt", + "@type": "DateTime" + }, + "object": { + "@id": "ngsi-ld:hasObject", + "@type": "@id" + }, + "objects": { + "@id": "ngsi-ld:hasObjects", + "@type": "@id", + "@container": "@list" + }, + "observationInterval": "ngsi-ld:observationInterval", + "observationSpace": "ngsi-ld:observationSpace", + "observedAt": { + "@id": "ngsi-ld:observedAt", + "@type": "DateTime" + }, + "operationSpace": "ngsi-ld:operationSpace", + "properties": "geojson:properties", + "propertyNames": { + "@id": "ngsi-ld:propertyNames", + "@type": "@vocab" + }, + "q": "ngsi-ld:q", + "reason": "ngsi-ld:reason", + "registrationName": "ngsi-ld:registrationName", + "relationshipNames": { + "@id": "ngsi-ld:relationshipNames", + "@type": "@vocab" + }, + "scope": "ngsi-ld:scope", + "scopeQ": "ngsi-ld:scopeQ", + "startAt": { + "@id": "ngsi-ld:startAt", + "@type": "DateTime" + }, + "status": "ngsi-ld:status", + "stddev": { + "@id": "ngsi-ld:stddev", + "@container": "@list" + }, + "subscriptionId": { + "@id": "ngsi-ld:subscriptionId", + "@type": "@id" + }, + "subscriptionName": "ngsi-ld:subscriptionName", + "success": { + "@id": "ngsi-ld:success", + "@type": "@id" + }, + "sum": { + "@id": "ngsi-ld:sum", + "@container": "@list" + }, + "sumsq": { + "@id": "ngsi-ld:sumsq", + "@container": "@list" + }, + "temporalQ": "ngsi-ld:temporalQ", + "tenant": { + "@id": "ngsi-ld:tenant", + "@type": "@id" + }, + "throttling": "ngsi-ld:throttling", + "timeAt": { + "@id": "ngsi-ld:timeAt", + "@type": "DateTime" + }, + "timeInterval": "ngsi-ld:timeInterval", + "timeproperty": "ngsi-ld:timeproperty", + "timerel": "ngsi-ld:timerel", + "timesSent": "ngsi-ld:timesSent", + "title": "http://purl.org/dc/terms/title", + "totalCount": { + "@id": "ngsi-ld:totalCount", + "@container": "@list" + }, + "triggerReason": "ngsi-ld:triggerReason", + "typeList": { + "@id": "ngsi-ld:typeList", + "@type": "@vocab" + }, + "typeName": { + "@id": "ngsi-ld:typeName", + "@type": "@vocab" + }, + "typeNames": { + "@id": "ngsi-ld:typeNames", + "@type": "@vocab" + }, + "unchanged": "ngsi-ld:unchanged", + "unitCode": "ngsi-ld:unitCode", + "updated": "ngsi-ld:updated", + "uri": "ngsi-ld:uri", + "value": "ngsi-ld:hasValue", + "values": { + "@id": "ngsi-ld:hasValues", + "@container": "@list" + }, + "watchedAttributes": { + "@id": "ngsi-ld:watchedAttributes", + "@type": "@vocab" + }, + "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" + } +} diff --git a/coreContext/ngsi-ld-core-context-v1.6.jsonld b/coreContext/ngsi-ld-core-context-v1.6.jsonld new file mode 100644 index 0000000..3f21a56 --- /dev/null +++ b/coreContext/ngsi-ld-core-context-v1.6.jsonld @@ -0,0 +1,299 @@ +{ + "@context": { + + "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", + "geojson": "https://purl.org/geojson/vocab#", + "id": "@id", + "type": "@type", + + "Attribute": "ngsi-ld:Attribute", + "AttributeList": "ngsi-ld:AttributeList", + "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", + "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", + "Date": "ngsi-ld:Date", + "DateTime": "ngsi-ld:DateTime", + "EntityType": "ngsi-ld:EntityType", + "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", + "EntityTypeList": "ngsi-ld:EntityTypeList", + "Feature": "geojson:Feature", + "FeatureCollection": "geojson:FeatureCollection", + "GeoProperty": "ngsi-ld:GeoProperty", + "GeometryCollection": "geojson:GeometryCollection", + "LineString": "geojson:LineString", + "LanguageProperty": "ngsi-ld:LanguageProperty", + "MultiLineString": "geojson:MultiLineString", + "MultiPoint": "geojson:MultiPoint", + "MultiPolygon": "geojson:MultiPolygon", + "Notification": "ngsi-ld:Notification", + "Point": "geojson:Point", + "Polygon": "geojson:Polygon", + "Property": "ngsi-ld:Property", + "Relationship": "ngsi-ld:Relationship", + "Subscription": "ngsi-ld:Subscription", + "TemporalProperty": "ngsi-ld:TemporalProperty", + "Time": "ngsi-ld:Time", + + "accept": "ngsi-ld:accept", + "attributeCount": "attributeCount", + "attributeDetails": "attributeDetails", + "attributeList": { + "@id": "ngsi-ld:attributeList", + "@type": "@vocab" + }, + "attributeName": { + "@id": "ngsi-ld:attributeName", + "@type": "@vocab" + }, + "attributeNames": { + "@id": "ngsi-ld:attributeNames", + "@type": "@vocab" + }, + "attributeTypes": { + "@id": "ngsi-ld:attributeTypes", + "@type": "@vocab" + }, + "attributes": { + "@id": "ngsi-ld:attributes", + "@type": "@vocab" + }, + "attrs": "ngsi-ld:attrs", + "avg": { + "@id": "ngsi-ld:avg", + "@container": "@list" + }, + "bbox": { + "@container": "@list", + "@id": "geojson:bbox" + }, + "cacheDuration": "ngsi-ld:cacheDuration", + + "contextSourceInfo": "ngsi-ld:contextSourceInfo", + "cooldown": "ngsi-ld:cooldown", + "coordinates": { + "@container": "@list", + "@id": "geojson:coordinates" + }, + "createdAt": { + "@id": "ngsi-ld:createdAt", + "@type": "DateTime" + }, + "csf": "ngsi-ld:csf", + "data": "ngsi-ld:data", + "datasetId": { + "@id": "ngsi-ld:datasetId", + "@type": "@id" + }, + "deletedAt": { + "@id": "ngsi-ld:deletedAt", + "@type": "DateTime" + }, + "description": "http://purl.org/dc/terms/description", + "detail": "ngsi-ld:detail", + "distinctCount": { + "@id": "ngsi-ld:distinctCount", + "@container": "@list" + }, + "endAt": { + "@id": "ngsi-ld:endAt", + "@type": "DateTime" + }, + "endTimeAt": { + "@id": "ngsi-ld:endTimeAt", + "@type": "DateTime" + }, + "endpoint": "ngsi-ld:endpoint", + "entities": "ngsi-ld:entities", + "entityCount": "ngsi-ld:entityCount", + "entityId": { + "@id": "ngsi-ld:entityId", + "@type": "@id" + }, + "error": "ngsi-ld:error", + "errors": "ngsi-ld:errors", + "expiresAt": { + "@id": "ngsi-ld:expiresAt", + "@type": "DateTime" + }, + "features": { + "@container": "@set", + "@id": "geojson:features" + }, + "format": "ngsi-ld:format", + "geoQ": "ngsi-ld:geoQ", + "geometry": "geojson:geometry", + "geoproperty": "ngsi-ld:geoproperty", + "georel": "ngsi-ld:georel", + "idPattern": "ngsi-ld:idPattern", + "information": "ngsi-ld:information", + "instanceId": { + "@id": "ngsi-ld:instanceId", + "@type": "@id" + }, + "isActive": "ngsi-ld:isActive", + "key": "ngsi-ld:hasKey", + "lang": "ngsi-ld:lang", + "languageMap": { + "@id": "ngsi-ld:hasLanguageMap", + "@container": "@language" + }, + "languageMaps": { + "@id": "ngsi-ld:hasLanguageMaps", + "@container": "@list" + }, + "lastFailure": { + "@id": "ngsi-ld:lastFailure", + "@type": "DateTime" + }, + "lastNotification": { + "@id": "ngsi-ld:lastNotification", + "@type": "DateTime" + }, + "lastSuccess": { + "@id": "ngsi-ld:lastSuccess", + "@type": "DateTime" + }, + "localOnly": "ngsi-ld:localOnly", + "location": "ngsi-ld:location", + "management": "ngsi-ld:management", + "managementInterval": "ngsi-ld:managementInterval", + "max": { + "@id": "ngsi-ld:max", + "@container": "@list" + }, + "min": { + "@id": "ngsi-ld:min", + "@container": "@list" + }, + "mode": "ngsi-ld:mode", + "modifiedAt": { + "@id": "ngsi-ld:modifiedAt", + "@type": "DateTime" + }, + "notification": "ngsi-ld:notification", + "notificationTrigger": "ngsi-ld:notificationTrigger", + "notifiedAt": { + "@id": "ngsi-ld:notifiedAt", + "@type": "DateTime" + }, + "notifierInfo": "ngsi-ld:notifierInfo", + "notUpdated": "ngsi-ld:notUpdated", + "object": { + "@id": "ngsi-ld:hasObject", + "@type": "@id" + }, + "objects": { + "@id": "ngsi-ld:hasObjects", + "@container": "@list" + }, + "observationInterval": "ngsi-ld:observationInterval", + "observationSpace": "ngsi-ld:observationSpace", + "observedAt": { + "@id": "ngsi-ld:observedAt", + "@type": "DateTime" + }, + "operationSpace": "ngsi-ld:operationSpace", + "operations": "ngsi-ld:operations", + "previousLanguageMap": { + "@id": "ngsi-ld:hasPreviousLanguageMap", + "@container": "@language" + }, + "previousObject": { + "@id": "ngsi-ld:hasPreviousObject", + "@type": "@id" + }, + "previousValue": "ngsi-ld:hasPreviousValue", + "properties": "geojson:properties", + "propertyNames": { + "@id": "ngsi-ld:propertyNames", + "@type": "@vocab" + }, + "q": "ngsi-ld:q", + "reason": "ngsi-ld:reason", + "receiverInfo": "ngsi-ld:receiverInfo", + "refreshRate": "ngsi-ld:refreshRate", + "registrationId": "ngsi-ld:registrationId", + "registrationName": "ngsi-ld:registrationName", + "relationshipNames": { + "@id": "ngsi-ld:relationshipNames", + "@type": "@vocab" + }, + "scope": "ngsi-ld:scope", + "scopeQ": "ngsi-ld:scopeQ", + "showChanges": "ngsi-ld:showChanges", + "startAt": { + "@id": "ngsi-ld:startAt", + "@type": "DateTime" + }, + "status": "ngsi-ld:status", + "stddev": { + "@id": "ngsi-ld:stddev", + "@container": "@list" + }, + "subscriptionId": { + "@id": "ngsi-ld:subscriptionId", + "@type": "@id" + }, + "subscriptionName": "ngsi-ld:subscriptionName", + "success": { + "@id": "ngsi-ld:success", + "@type": "@id" + }, + "sum": { + "@id": "ngsi-ld:sum", + "@container": "@list" + }, + "sumsq": { + "@id": "ngsi-ld:sumsq", + "@container": "@list" + }, + "sysAttrs": "ngsi-ld:sysAttrs", + "temporalQ": "ngsi-ld:temporalQ", + "tenant": { + "@id": "ngsi-ld:tenant", + "@type": "@id" + }, + "throttling": "ngsi-ld:throttling", + "timeAt": { + "@id": "ngsi-ld:timeAt", + "@type": "DateTime" + }, + "timeInterval": "ngsi-ld:timeInterval", + "timeout": "ngsi-ld:timeout", + "timeproperty": "ngsi-ld:timeproperty", + "timerel": "ngsi-ld:timerel", + "timesFailed": "ngsi-ld:timesFailed", + "timesSent": "ngsi-ld:timesSent", + "title": "http://purl.org/dc/terms/title", + "totalCount": { + "@id": "ngsi-ld:totalCount", + "@container": "@list" + }, + "triggerReason": "ngsi-ld:triggerReason", + "typeList": { + "@id": "ngsi-ld:typeList", + "@type": "@vocab" + }, + "typeName": { + "@id": "ngsi-ld:typeName", + "@type": "@vocab" + }, + "typeNames": { + "@id": "ngsi-ld:typeNames", + "@type": "@vocab" + }, + "unchanged": "ngsi-ld:unchanged", + "unitCode": "ngsi-ld:unitCode", + "updated": "ngsi-ld:updated", + "uri": "ngsi-ld:uri", + "value": "ngsi-ld:hasValue", + "values": { + "@id": "ngsi-ld:hasValues", + "@container": "@list" + }, + "watchedAttributes": { + "@id": "ngsi-ld:watchedAttributes", + "@type": "@vocab" + }, + "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" + } +} diff --git a/examples/@context_C.2.4.json b/examples/@context_C.2.4.json new file mode 100644 index 0000000..adfe278 --- /dev/null +++ b/examples/@context_C.2.4.json @@ -0,0 +1,42 @@ +{ + "id": "@id", + "type": "@type", + "Property": "https://uri.etsi.org/ngsi-ld/Property", + "Relationship": "https://uri.etsi.org/ngsi-ld/Relationship", + "value": "https://uri.etsi.org/ngsi-ld/hasValue", + "object": { + "@type": "@id", + "@id": "https://uri.etsi.org/ngsi-ld/hasObject" + }, + "observedAt": { + "@type": "https://uri.etsi.org/ngsi-ld/DateTime", + "@id": "https://uri.etsi.org/ngsi-ld/observedAt" + }, + "datasetId": { + "@id": "https://uri.etsi.org/ngsi-ld/datasetId", + "@type": "@id" + }, + "location": "https://uri.etsi.org/ngsi-ld/location", + "GeoProperty": "https://uri.etsi.org/ngsi-ld/GeoProperty", + "Vehicle": "http://example.org/vehicle/Vehicle", + "street": "http://example.org/vehicle/street", + "brandName": "http://example.org/vehicle/brandName", + "speed": "http://example.org/vehicle/speed", + "isParked": { + "@type": "@id", + "@id": "http://example.org/common/isParked" + }, + "OffStreetParking": "http://example.org/parking/OffStreetParking", + "availableSpotNumber": "http://example.org/parking/availableSpotNumber", + "totalSpotNumber": "http://example.org/parking/totalSpotNumber", + "isNextToBuilding": { + "@type": "@id", + "@id": "http://example.org/common/isNextToBuilding" + }, + "reliability": "http://example.org/common/reliability", + "providedBy": { + "@type": "@id", + "@id": "http://example.org/common/providedBy" + }, + "name": "http://example.org/common/name" +} diff --git a/examples/AttributeList_C.5.10.3.json b/examples/AttributeList_C.5.10.3.json new file mode 100644 index 0000000..402c0d5 --- /dev/null +++ b/examples/AttributeList_C.5.10.3.json @@ -0,0 +1,11 @@ +{ + "id": "urn:ngsi-ld:AttributeList:56534657", + "type": "AttributeList", + "attributeList": [ + "brandName", + "isParked", + "location", + "speed", + "http://example.org/parking/status" + ] +} diff --git a/examples/Attribute_C.5.12.3.json b/examples/Attribute_C.5.12.3.json new file mode 100644 index 0000000..0c76ae3 --- /dev/null +++ b/examples/Attribute_C.5.12.3.json @@ -0,0 +1,8 @@ +{ + "id": "http://example.org/vehicle/brandName", + "type": "Attribute", + "attributeName": "brandName", + "attributeTypes": ["Property"], + "typeNames": ["Vehicle"], + "attributeCount": 2 +} diff --git a/examples/Attributes_details_C.5.11.3.json b/examples/Attributes_details_C.5.11.3.json new file mode 100644 index 0000000..e13f747 --- /dev/null +++ b/examples/Attributes_details_C.5.11.3.json @@ -0,0 +1,36 @@ +[ + { + "id": "http://example.org/vehicle/brandName", + "type": "Attribute", + "attributeName": "brandName", + "typeNames": ["Vehicle"] + }, + { + "id": "http://example.org/vehicle/isParked", + "type": "Attribute", + "attributeName": "isParked", + "typeNames": ["Vehicle"] + }, + { + "id": "https://uri.etsi.org/ngsi-ld/location", + "type": "Attribute", + "attributeName": "location", + "typeNames": [ + "Vehicle", + "OffStreetParking", + "http://example.org/parking/ParkingSpot" + ] + }, + { + "id": "http://example.org/vehicle/speed", + "type": "Attribute", + "attributeName": "speed", + "typeNames": ["Vehicle"] + }, + { + "id": "http://example.org/parking/status", + "type": "Attribute", + "attributeName": "http://example.org/parking/status", + "typeNames": ["http://example.org/parking/ParkingSpot"] + } +] diff --git a/examples/ContextSourceRegistration_C.3.json b/examples/ContextSourceRegistration_C.3.json new file mode 100644 index 0000000..1e67268 --- /dev/null +++ b/examples/ContextSourceRegistration_C.3.json @@ -0,0 +1,52 @@ +{ + "id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456", + "type": "ContextSourceRegistration", + "information": [ + { + "entities": [ + { + "id": "urn:ngsi-ld:Vehicle:A456", + "type": "Vehicle" + } + ], + "propertyNames": ["brandName", "speed"], + "relationshipNames": ["isParked"] + }, + { + "entities": [ + { + "idPattern": ".*downtown$", + "type": "OffStreetParking" + }, + { + "idPattern": ".*47$", + "type": "OffStreetParking" + } + ], + "propertyNames": ["availableSpotNumber", "totalSpotNumber"], + "relationshipNames": ["isNextToBuilding"] + } + ], + "endpoint": "http://my.csource.org:1026", + "location": { + "type": "Polygon", + "coordinates": [ + [ + [100.0, 0.0], + [101.0, 0.0], + [101.0, 1.0], + [100.0, 1.0], + [100.0, 0.0] + ] + ] + }, + "timestamp": { + "startAt": " 2017-11-29T14:53:15Z" + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/EntityList_C.5.4.3.json b/examples/EntityList_C.5.4.3.json new file mode 100644 index 0000000..6cf6e26 --- /dev/null +++ b/examples/EntityList_C.5.4.3.json @@ -0,0 +1,20 @@ +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "brandName": "Volvo", + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:Vehicle:A456", + "type": "Vehicle", + "brandName": "Mercedes", + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/examples/EntityTemporal_C.5.5.3.json b/examples/EntityTemporal_C.5.5.3.json new file mode 100644 index 0000000..3b4e641 --- /dev/null +++ b/examples/EntityTemporal_C.5.5.3.json @@ -0,0 +1,27 @@ +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 120, + "observedAt": "2018-08-01T12:03:00Z" + }, + { + "type": "Property", + "value": 80, + "observedAt": "2018-08-01T12:05:00Z" + }, + { + "type": "Property", + "value": 100, + "observedAt": "2018-08-01T12:07:00Z" + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/examples/EntityTemporal_simplified_C.5.6.3.json b/examples/EntityTemporal_simplified_C.5.6.3.json new file mode 100644 index 0000000..dd97806 --- /dev/null +++ b/examples/EntityTemporal_simplified_C.5.6.3.json @@ -0,0 +1,18 @@ +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": { + "type": "Property", + "values": [ + [120, "2018-08-01T12:03:00Z"], + [80, "2018-08-01T12:05:00Z"], + [100, "2018-08-01T12:07:00Z"] + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/examples/EntityTypeInfo_C.5.9.3.json b/examples/EntityTypeInfo_C.5.9.3.json new file mode 100644 index 0000000..4a0f4d2 --- /dev/null +++ b/examples/EntityTypeInfo_C.5.9.3.json @@ -0,0 +1,32 @@ +{ + "id": "http://example.org/vehicle/Vehicle", + "type": "EntityTypeInfo", + "typeName": "Vehicle", + "entityCount": 2, + "attributeDetails": [ + { + "id": "http://example.org/vehicle/brandName", + "type": "Attribute", + "attributeName": "brandName", + "attributeTypes": ["Property"] + }, + { + "id": "http://example.org/vehicle/isParked", + "type": "Attribute", + "attributeName": "isParked", + "attributeTypes": ["Relationship"] + }, + { + "id": "https://uri.etsi.org/ngsi-ld/location", + "type": "Attribute", + "attributeName": "location", + "attributeTypes": ["GeoProperty"] + }, + { + "id": "http://example.org/vehicle/speed", + "type": "Attribute", + "attributeName": "speed", + "attributeTypes": ["Property"] + } + ] +} diff --git a/examples/EntityTypeList_C.5.7.json b/examples/EntityTypeList_C.5.7.json new file mode 100644 index 0000000..640ef0e --- /dev/null +++ b/examples/EntityTypeList_C.5.7.json @@ -0,0 +1,9 @@ +{ + "id": "urn:ngsi-ld:EntityTypeList:34534657", + "type": "EntityTypeList", + "typeList": [ + "Vehicle", + "OffStreetParking", + "http://example.org/parking/ParkingSpot" + ] +} diff --git a/examples/EntityType_C.5.8.3.json b/examples/EntityType_C.5.8.3.json new file mode 100644 index 0000000..a98c453 --- /dev/null +++ b/examples/EntityType_C.5.8.3.json @@ -0,0 +1,25 @@ +[ + { + "id": "http://example.org/vehicle/Vehicle", + "type": "EntityType", + "typeName": "Vehicle", + "attributeNames": ["brandName", "isParked", "location", "speed"] + }, + { + "id": "http://example.org/parking/OffStreetParking", + "type": "EntityType", + "typeName": "OffStreetParking", + "attributeNames": [ + "availableSpotNumber", + "isNextToBuilding", + "location", + "totalSpotNumber" + ] + }, + { + "id": "http://example.org/parking/ParkingSpot", + "type": "EntityType", + "typeName": "http://example.org/parking/ParkingSpot", + "attributeNames": ["location", "http://example.org/parking/status"] + } +] diff --git a/examples/Entity_lang_C.5.13.3.json b/examples/Entity_lang_C.5.13.3.json new file mode 100644 index 0000000..c0b84bd --- /dev/null +++ b/examples/Entity_lang_C.5.13.3.json @@ -0,0 +1,11 @@ +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "marque": "Opel Karl", + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/examples/FeatureCollection_concise_C.2.3.json b/examples/FeatureCollection_concise_C.2.3.json new file mode 100644 index 0000000..f1f05ed --- /dev/null +++ b/examples/FeatureCollection_concise_C.2.3.json @@ -0,0 +1,59 @@ +{ + "type": "FeatureCollection", + "features": [ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.5, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": { + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.7, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown2", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown Two", + "availableSpotNumber": { + "value": 99, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.8, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C2" + } + }, + "totalSpotNumber": 100, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/FeatureCollection_normalized_C.2.3.json b/examples/FeatureCollection_normalized_C.2.3.json new file mode 100644 index 0000000..c4d6bcb --- /dev/null +++ b/examples/FeatureCollection_normalized_C.2.3.json @@ -0,0 +1,87 @@ +{ + "type": "FeatureCollection", + "features": [ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.5, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown2", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown Two" + }, + "availableSpotNumber": { + "type": "Property", + "value": 99, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.8 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C2" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 100 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/FeatureCollection_simplified_C.2.3.json b/examples/FeatureCollection_simplified_C.2.3.json new file mode 100644 index 0000000..92663ff --- /dev/null +++ b/examples/FeatureCollection_simplified_C.2.3.json @@ -0,0 +1,45 @@ +{ + "type": "FeatureCollection", + "features": [ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.5, 41.2] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": 121, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.5, 41.2] + } + } + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown2", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown Two", + "availableSpotNumber": 99, + "totalSpotNumber": 100, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + } + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Feature_concise_C.2.3.json b/examples/Feature_concise_C.2.3.json new file mode 100644 index 0000000..07d2879 --- /dev/null +++ b/examples/Feature_concise_C.2.3.json @@ -0,0 +1,29 @@ +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": { + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.7, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "totalSpotNumber": 200, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +} diff --git a/examples/Feautre_keyValues_C.2.3.json b/examples/Feautre_keyValues_C.2.3.json new file mode 100644 index 0000000..725459a --- /dev/null +++ b/examples/Feautre_keyValues_C.2.3.json @@ -0,0 +1,22 @@ +{ + "id": "urn:ngsi-ld:offstreetparking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": 121, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Feautre_normalized_C.2.3.json b/examples/Feautre_normalized_C.2.3.json new file mode 100644 index 0000000..8349d5c --- /dev/null +++ b/examples/Feautre_normalized_C.2.3.json @@ -0,0 +1,43 @@ +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "Feature", + "geometry": { + "type": "Point", + "coordinates": [-8.51, 41.1] + }, + "properties": { + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.51, 41.1] + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +} diff --git a/examples/OffStreetParking_concise_C.2.3.json b/examples/OffStreetParking_concise_C.2.3.json new file mode 100644 index 0000000..2c913a8 --- /dev/null +++ b/examples/OffStreetParking_concise_C.2.3.json @@ -0,0 +1,22 @@ +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": { + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": 0.7, + "providedBy": { + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.5, 41.2] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/OffStreetParking_normalized_C.2.3.json b/examples/OffStreetParking_normalized_C.2.3.json new file mode 100644 index 0000000..aa2d962 --- /dev/null +++ b/examples/OffStreetParking_normalized_C.2.3.json @@ -0,0 +1,36 @@ +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.5, 41.2] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/OffStreetParking_simplified_C.2.3.json b/examples/OffStreetParking_simplified_C.2.3.json new file mode 100644 index 0000000..7c05d9e --- /dev/null +++ b/examples/OffStreetParking_simplified_C.2.3.json @@ -0,0 +1,15 @@ +{ + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "name": "Downtown One", + "availableSpotNumber": 121, + "totalSpotNumber": 200, + "location": { + "type": "Point", + "coordinates": [-8.5, 41.2] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Subscription_C.4.json b/examples/Subscription_C.4.json new file mode 100644 index 0000000..f8ec051 --- /dev/null +++ b/examples/Subscription_C.4.json @@ -0,0 +1,28 @@ +{ + "id": "urn:ngsi-ld:Subscription:mySubscription", + "type": "Subscription", + "entities": [ + { + "type": "Vehicle" + } + ], + "watchedAttributes": ["speed"], + "q": "speed>50", + "geoQ": { + "georel": "near;maxDistance==2000", + "geometry": "Point", + "coordinates": [-1, 100] + }, + "notification": { + "attributes": ["speed"], + "format": "keyValues", + "endpoint": { + "uri": "http://my.endpoint.org/notify", + "accept": "application/json" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_MultiAttribute_C.2.2.json b/examples/Vehicle_MultiAttribute_C.2.2.json new file mode 100644 index 0000000..fb82830 --- /dev/null +++ b/examples/Vehicle_MultiAttribute_C.2.2.json @@ -0,0 +1,32 @@ +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 55, + "source": { + "type": "Property", + "value": "Speedometer" + }, + "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed" + }, + { + "type": "Property", + "value": 54.5, + "source": { + "type": "Property", + "value": "GPS" + }, + "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed" + } + ], + "@context": [ + { + "Vehicle": "http://example.org/Vehicle", + "speed": "http://example.org/speed", + "source": "http://example.org/hasSource" + }, + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_concise_C.2.2.json b/examples/Vehicle_concise_C.2.2.json new file mode 100644 index 0000000..46954da --- /dev/null +++ b/examples/Vehicle_concise_C.2.2.json @@ -0,0 +1,24 @@ +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_concise_lang_C.2.2.json b/examples/Vehicle_concise_lang_C.2.2.json new file mode 100644 index 0000000..491a18d --- /dev/null +++ b/examples/Vehicle_concise_lang_C.2.2.json @@ -0,0 +1,22 @@ +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "value": "Grand Place", + "lang": "fr" + }, + "isParked": { + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_datetime_C.6.json b/examples/Vehicle_datetime_C.6.json new file mode 100644 index 0000000..325e001 --- /dev/null +++ b/examples/Vehicle_datetime_C.6.json @@ -0,0 +1,15 @@ +{ + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "testedAt": { + "type": "Property", + "value": { + "@type": "DateTime", + "@value": "2018-12-04T12:00:00Z" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_keyValues_C.2.2.json b/examples/Vehicle_keyValues_C.2.2.json new file mode 100644 index 0000000..6069310 --- /dev/null +++ b/examples/Vehicle_keyValues_C.2.2.json @@ -0,0 +1,16 @@ +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": { + "fr": "Grand Place", + "nl": "Grote Markt" + }, + "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_keyValues_lang_C.2.2.json b/examples/Vehicle_keyValues_lang_C.2.2.json new file mode 100644 index 0000000..4e58b6d --- /dev/null +++ b/examples/Vehicle_keyValues_lang_C.2.2.json @@ -0,0 +1,13 @@ +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": "Mercedes", + "street": "Grand Place", + "isParked": "urn:ngsi-ld:OffStreetParking:Downtown1", + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_normalized_C.2.2.json b/examples/Vehicle_normalized_C.2.2.json new file mode 100644 index 0000000..af471c0 --- /dev/null +++ b/examples/Vehicle_normalized_C.2.2.json @@ -0,0 +1,30 @@ +{ + "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", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_normalized_lang_C.2.2.json b/examples/Vehicle_normalized_lang_C.2.2.json new file mode 100644 index 0000000..3c6e49f --- /dev/null +++ b/examples/Vehicle_normalized_lang_C.2.2.json @@ -0,0 +1,28 @@ +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": { + "type": "Property", + "value": "Mercedes" + }, + "street": { + "type": "Property", + "value": "Grand Place", + "lang": "fr" + }, + "isParked": { + "type": "Relationship", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/commonTerms.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] +} diff --git a/examples/Vehicle_scope_C.5.15.3.json b/examples/Vehicle_scope_C.5.15.3.json new file mode 100644 index 0000000..08d6d4c --- /dev/null +++ b/examples/Vehicle_scope_C.5.15.3.json @@ -0,0 +1,76 @@ +[ + { + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "scope": "/Madrid/Centro", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.5, 41.2] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:OffStreetParking:Corte4", + "type": "OffStreetParking", + "scope": ["/Madrid/Cortes", "/Company894/UnitC"], + "name": { + "type": "Property", + "value": "Corte4" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 100 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.6, 41.3] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/examples/Vehicle_temporal_aggregated_C.5.14.3.json b/examples/Vehicle_temporal_aggregated_C.5.14.3.json new file mode 100644 index 0000000..c27a531 --- /dev/null +++ b/examples/Vehicle_temporal_aggregated_C.5.14.3.json @@ -0,0 +1,21 @@ +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": { + "type": "Property", + "max": [ + [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], + [100, "2018-08-01T12:04:00Z", "2018-08-01T12:08:00Z"] + ], + "avg": [ + [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], + [90, "2018-08-01T12:04:00Z", "2018-08-01T12:08:00Z"] + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/examples/Vehicle_temporal_scope_C.5.16.3.json b/examples/Vehicle_temporal_scope_C.5.16.3.json new file mode 100644 index 0000000..2e7676e --- /dev/null +++ b/examples/Vehicle_temporal_scope_C.5.16.3.json @@ -0,0 +1,44 @@ +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "scope": { + "type": "Property", + "values": ["/Madrid/Centro", "2018-08-01T11:00:00Z"] + }, + "speed": { + "type": "Property", + "values": [ + [30, "2018-08-01T12:03:00Z"], + [60, "2018-08-01T12:05:00Z"], + [50, "2018-08-01T12:07:00Z"] + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + }, + { + "id": "urn:ngsi-ld:Vehicle:A8311", + "type": "Vehicle", + "scope": { + "type": "Property", + "values": [ + [["/Madrid/Centro", "/Company123/UnitA"], "2018-08-01T12:10:00Z"] + ] + }, + "speed": { + "type": "Property", + "values": [ + [40, "2018-08-01T12:12:00Z"], + [60, "2018-08-01T12:14:00Z"], + [50, "2018-08-01T12:16:00Z"] + ] + }, + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" + ] + } +] diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml new file mode 100644 index 0000000..704a431 --- /dev/null +++ b/ngsi-ld-api.yaml @@ -0,0 +1,5236 @@ +openapi: 3.0.3 +info: + title: NGSI-LD API + version: 1.6.1 + description: ETSI GS CIM 009 V1.6.1 cross-cutting Context Information Management (CIM); NGSI-LD API. + contact: + url: https://www.etsi.org/committee/cim + license: + name: BSD-3-Clause + url: https://forge.etsi.org/legal-matters + +externalDocs: + description: ETSI GS CIM 009 V1.6.1 cross-cutting Context Information Management (CIM); NGSI-LD API + url: https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.06.01_60/gs_CIM009v010601p.pdf + +servers: + - url: '{protocol}://{hostname}:{port}/ngsi-ld/v1' + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost + port: + default: '443' + +paths: + /entities: + post: + tags: + - Context Information Provision + summary: | + Entity creation + description: | + 5.6.1 Create Entity + + This operation allows creating a new NGSI-LD Entity. + operationId: createEntity + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents the entity that is to be created. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created entity resource. + headers: + Location: + $ref: '#/components/headers/Location' + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + headers: + Location: + $ref: '#/components/headers/Location' + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Context Information Consumption + summary: | + Query entities + description: | + 5.7.2 Query Entities (excluding batch entity queries). + + This operation allows querying an NGSI-LD system. + operationId: queryEntity + parameters: + # Query params + - $ref: '#/components/parameters/Query.id' + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.idPattern' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.q' + - $ref: '#/components/parameters/Query.csf' + - $ref: '#/components/parameters/Query.geometry' + - $ref: '#/components/parameters/Query.georel' + - $ref: '#/components/parameters/Query.coordinates' + - $ref: '#/components/parameters/Query.geoproperty' + - $ref: '#/components/parameters/Query.geometryProperty' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + - $ref: '#/components/parameters/Query.options.entities' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the query result as a list of entities, unless the Accept Header + indicates that the Entities are to be rendered as GeoJSON. + + If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body + containing the query result as GeoJSON FeatureCollection is returned. + headers: + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + application/geo+json: + schema: + $ref: '#/components/schemas/FeatureCollection' + '400': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/BadRequest' + + /entities/{entityId}: + get: + tags: + - Context Information Consumption + summary: | + Entity retrieval by id + description: | + 5.7.1 Retrieve Entity. + + This operation allows retrieving an NGSI-LD Entity. + operationId: retrieveEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.geometryProperty' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.options.entities' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the target entity containing the selected + Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON. + + If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON Feature is returned. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + application/geo+json: + schema: + $ref: '#/components/schemas/Feature' + '400': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/BadRequest' + '404': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Information Provision + summary: | + Entity deletion by id + description: | + 5.6.6 Delete entity. + + This operation allows deleting an NGSI-LD Entity. + operationId: deleteEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + $ref: '#/components/responses/BadRequest' + '404': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Information Provision + summary: | + Entity merge by id + description: | + 5.6.17 Merge entity. + + This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch + processing rules defined in IETF RFC 7396 by adding new Attributes (Properties or Relationships) + or modifying or deleting existing Attributes associated with an existing Entity. + operationId: mergeEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.representation' + required: false + - $ref: '#/components/parameters/Query.observedAt' + - $ref: '#/components/parameters/Query.lang' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Attributes to be merged. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + responses: + '204': + description: | + All the Attributes were merged successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + put: + tags: + - Context Information Provision + summary: | + Entity replacement by id + description: | + 5.6.18 Replace entity. + + This operation allows the modification of an existing NGSI-LD Entity + by replacing all of the Attributes (Properties or Relationships). + operationId: replaceEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Entity to be replaced. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + responses: + '204': + description: | + The entity was replaced successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + + /entities/{entityId}/attrs: + post: + tags: + - Context Information Provision + summary: | + Append attributes to Entity + description: | + 5.6.3 Append Entity attributes. + + This operation allows modifying an NGSI-LD Entity by adding + new attributes (Properties or Relationships). + operationId: appendAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.options.noOverwrite' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Attributes to be added. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + responses: + '204': + description: | + All the Attributes were appended successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + + patch: + tags: + - Context Information Provision + summary: | + Update attributes of an Entity + description: | + 5.6.2 Update Entity attributes. + + This operation allows modifying an existing NGSI-LD Entity by updating + already existing Attributes (Properties or Relationships). + operationId: updateEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Attributes to be updated. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + responses: + '204': + description: | + All the Attributes were appended successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /entities/{entityId}/attrs/{attrId}: + patch: + tags: + - Context Information Provision + summary: | + Partial Attribute update + description: | + 5.6.4 Partial Attribute update. + + This operation allows performing a partial update on an NGSI-LD Entity's Attribute (Property or Relationship). + A partial update only changes the elements provided in an Entity Fragment, leaving the rest as they are. + This operation supports the deletion of sub-Attributes but not the deletion of the whole Attribute itself. + operationId: updateAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Attribute Fragment containing the elements of the attribute to be updated. + $ref: '#/components/requestBodies/AttributeFragment' + responses: + '204': + description: | + The attribute was updated successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Information Provision + summary: | + Attribute delete + description: | + 5.6.5 Delete Entity Attribute. + operationId: deleteAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Query params + - $ref: '#/components/parameters/Query.deleteAll' + - $ref: '#/components/parameters/Query.datasetId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + The attribute was deleted successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + put: + tags: + - Context Information Provision + summary: | + Attribute replace + description: | + 5.6.19 Attribute replace. + + This operation allows the replacement of a single Attribute (Property or Relationship) + within an NGSI-LD Entity. + operationId: replaceAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Attribute Fragment replacing the previous data. + $ref: '#/components/requestBodies/AttributeFragment' + responses: + '204': + description: | + The attribute was replaced successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /csourceRegistrations: + post: + tags: + - Context Source Registration + summary: | + Csource registration creation + description: | + 5.9.2 Register Context Source. + + This operation allows registering a context source within an NGSI-LD system. + operationId: createCSR + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents + the context source registration that is to be created. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - type + - information + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - type + - information + - '@context' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created context source registration resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Context Source Discovery + summary: | + Discover Csource registrations + description: | + 5.10.2 Query Context Source Registrations. + + This operation allows discovering context source registrations from an NGSI-LD system. + The behaviour of the discovery of context source registrations differs significantly from + the querying of entities as described in clause 5.7.2. The approach is that the client + submits a query for entities as described in clause 5.7.2, but instead of receiving + the Entity information, it receives a list of Context Source Registrations describing + Context Sources that possibly have some of the requested Entity information. This means + that the requested Entities and Attributes are matched against the 'information' property + as described in clause 5.12. + + If no temporal query is present, only Context Source Registrations for Context Sources + providing latest information, i.e. without specified time intervals, are considered. + If a temporal query is present only Context Source Registrations with matching time intervals, + i.e. observationInterval or managementInterval, are considered. + operationId: queryCSR + parameters: + # Query params + - $ref: '#/components/parameters/Query.id' + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.idPattern' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.q' + - $ref: '#/components/parameters/Query.csf' + - $ref: '#/components/parameters/Query.geometry' + - $ref: '#/components/parameters/Query.georel' + - $ref: '#/components/parameters/Query.coordinates' + - $ref: '#/components/parameters/Query.geoproperty' + - $ref: '#/components/parameters/Query.timeproperty' + - $ref: '#/components/parameters/Query.timerel' + - $ref: '#/components/parameters/Query.timeAt' + - $ref: '#/components/parameters/Query.endTimeAt' + - $ref: '#/components/parameters/Query.geometryProperty' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.options.sysAttrs' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the query result as an array of context source registrations. + headers: + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - id + - type + - information + - endpoint + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - information + - endpoint + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /csourceRegistrations/{registrationId}: + get: + tags: + - Context Source Discovery + summary: | + Csource registration retrieval by id + description: | + 5.10.1 Retrieve Context Source Registration. + + This operation allows retrieving a specific context source registration from an NGSI-LD system. + operationId: retrieveCSR + parameters: + # Path params + - $ref: '#/components/parameters/Path.registrationId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the target subscription. + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - id + - type + - information + - endpoint + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - information + - endpoint + - '@context' + '400': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/BadRequest' + '404': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Source Registration + summary: | + Csource registration update by id + description: | + 5.9.3 Update Context Source Registration. + + This operation allows updating a Context Source Registration in an NGSI-LD system. + operationId: updateCSR + parameters: + # Path params + - $ref: '#/components/parameters/Path.registrationId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents + the context source registration that is to be updated. + content: + application/json: + schema: + $ref: '#/components/schemas/CsourceRegistration' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + responses: + '204': + description: | + The context source registration was successfully updated. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Source Registration + summary: | + Csource registration deletion by id + description: | + 5.9.4 Delete Context Source Registration. + + This operation allows deleting a Context Source Registration from an NGSI-LD system. + operationId: deleteCSR + parameters: + # Path params + - $ref: '#/components/parameters/Path.registrationId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /subscriptions: + post: + tags: + - Context Information Subscription + summary: | + Create Subscription + description: | + 5.8.1 Create subscription. + + This operation allows creating a new subscription. + operationId: createSubscription + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents the subscription that is to be created. + $ref: '#/components/requestBodies/Subscription' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains the resource URI + of the created subscription resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + get: + tags: + - Context Information Consumption + summary: | + Retrieve list of Subscriptions + description: | + 5.8.4 Query Subscriptions. + + This operation allows querying existing Subscriptions. + operationId: querySubscription + parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing a list of subscriptions. + headers: + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Subscription' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - notification + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /subscriptions/{subscriptionId}: + get: + tags: + - Context Information Consumption + summary: | + Subscription retrieval by id + description: | + 5.8.3 Retrieve Subscription. + + This operation allows retrieving an existing subscription. + operationId: retrieveSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the target subscription. + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - notification + - '@context' + '400': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/BadRequest' + '404': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Information Subscription + summary: | + Subscription update by id + description: | + 5.8.2 Update Subscription. + + This operation allows updating an existing subscription. + operationId: updateSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Subscription Fragment including id, type and any other subscription field to be changed. + $ref: '#/components/requestBodies/SubscriptionFragment' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Information Subscription + summary: | + Subscription deletion by id + description: | + 5.8.5 Delete Subscription. + + This operation allows deleting an existing subscription. + operationId: deleteSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /csourceSubscriptions: + post: + tags: + - Context Source Registration Subscription + summary: | + Create subscription to Csource registration + description: | + 5.11.2 Create Context Source Registration Subscription. + + This operation allows creating a new Context Source Registration Subscription. + operationId: createCSRSubscription + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents + the context source registration that is to be created. + $ref: '#/components/requestBodies/Subscription' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created context source registration subscription resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Context Source Registration Subscription + summary: | + Retrieval of list of subscriptions to Csource registrations + description: | + 5.11.5 Query Context Source Registration Subscriptions. + + This operation allows querying existing Context Source Registration Subscriptions. + operationId: queryCSRSubscription + parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing a list of context source registration subscriptions. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Subscription' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - notification + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /csourceSubscriptions/{subscriptionId}: + get: + tags: + - Context Source Registration Subscription + summary: | + Retrieval of subscription to Csource registration by id + description: | + 5.11.4 Retrieve Context Source Registration Subscription. + + This operation allows retrieving an existing Context Source Registration Subscription. + operationId: retrieveCSRSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of + the target context source registration subscription. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - notification + - '@context' + '400': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/BadRequest' + '404': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Source Registration Subscription + summary: | + Csource registration subscription update by id + description: | + 5.11.3 Update Context Source Registration Subscription. + + This operation allows updating an existing Context Source Registration Subscription. + operationId: updateCSRSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Subscription Fragment including id, type and any other context + source registration subscription field to be changed. + $ref: '#/components/requestBodies/SubscriptionFragment' + responses: + '204': + description: | + The context source registration subscription was successfully updated. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Source Registration + summary: | + Csource registration subscription deletion by id + description: | + 5.11.6 Delete Context Source Registration Subscription. + + This operation allows deleting an existing Context Source Registration Subscription. + operationId: deleteCSRSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /entityOperations/create: + post: + tags: + - Context Information Provision + summary: | + Batch Entity creation + description: | + 5.6.7 Batch Entity Creation. + + This operation allows creating a batch of NGSI-LD Entities. + operationId: createBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of entities to be created. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + responses: + '201': + description: | + If all entities have been successfully created, an array of Strings containing URIs + is returned in the response. Each URI represents the Entity Id of a created entity. + There is no restriction as to the order of the Entity Ids. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + type: string + application/json+ld: + schema: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - type: array + items: + type: string + '207': + description: | + If only some or none of the entities have been successfully created, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/upsert: + post: + tags: + - Context Information Provision + summary: | + Batch Entity create or update (upsert) + description: | + 5.6.8 Batch Entity Upsert. + + This operation allows creating a batch of NGSI-LD Entities, updating each of them if they already existed. + In some database jargon this kind of operation is known as "upsert". + operationId: upsertBatch + parameters: + # Query parameters + - $ref: '#/components/parameters/Query.options.upsert' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of entities to be created. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + responses: + '201': + description: | + If all entities not existing prior to this request have been successfully created and + the others have been successfully updated, an array of String (with the URIs representing the + Entity Ids of the created entities only) is returned in the response. There is no restriction as to + the order of the Entity Ids. The merely updated entities do not take part in the response + (corresponding to 204 No Content returned in the case of updates). + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + type: string + application/json+ld: + schema: + type: array + items: + type: string + '204': + description: | + If all entities already existed and are successfully updated, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If only some or none of the entities have been successfully created, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/update: + post: + tags: + - Context Information Provision + summary: | + Batch Entity update + description: | + 5.6.9 Batch Entity Update. + + This operation allows updating a batch of NGSI-LD Entities. + operationId: updateBatch + parameters: + # Query parameters + - $ref: '#/components/parameters/Query.options.noOverwrite' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of entities to be updated. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + responses: + '204': + description: | + If all entities already existed and are successfully updated, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If only some or none of the entities have been successfully created, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/delete: + post: + tags: + - Context Information Provision + summary: | + Batch Entity delete + description: | + 5.6.10 Batch Entity Delete. + + This operation allows deleting a batch of NGSI-LD Entities. + operationId: deleteBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of String (URIs representing Entity IDs) to be deleted. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + responses: + '204': + description: | + If all entities existed and have been successfully deleted, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If some or all of the entities have not been successfully deleted, or did not exist, + a response body containing the result of each operation contained in the batch is returned + in a BatchOperationResult structure. It contains two arrays. The first array ('success') contains + the URIs of the successfully deleted entities, while the second array ('errors') + contains information about the error for each of the entities that could not be deleted. + There is no restriction as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration is returned + in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, + fails or times out, see clause 6.3.17. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/query: + post: + tags: + - Context Information Consumption + summary: | + Query entities based on POST + description: | + 5.7.2 Query Entity. + operationId: queryBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Payload body in the request contains a JSON-LD object which represents the query to be performed. + $ref: '#/components/requestBodies/Query' + responses: + '200': + description: | + A response body containing the query result as a list of Entities. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/merge: + post: + tags: + - Context Information Provision + summary: | + Batch Entity merge + description: | + 5.6.20 Batch Entity Merge. + + This operation allows modification of a batch of NGSI-LD Entities according to the JSON Merge Patch + processing rules defined in IETF RFC 7396 by adding new attributes (Properties or Relationships) + or modifying or deleting existing attributes associated with an existing Entity. + operationId: mergeBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of Entities to be merged. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + responses: + '204': + description: | + If all entities have been successfully merged, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If only some or none of the entities have been successfully merged, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /temporal/entities: + post: + tags: + - Temporal Context Information Provision + summary: | + Temporal Representation of Entity creation + description: | + 5.6.11 Upsert Temporal Representation. + + This operation allows creating or updating (by adding new Attribute instances) + a Temporal Representation of an Entity. + operationId: upsertTemporal + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents the + temporal representation of the entity that is to be created (or updated). + $ref: '#/components/requestBodies/EntityTemporal' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created entity resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '204': + description: | + Upon update success. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Temporal Context Information Consumption + summary: | + Query temporal evolution of Entities + description: | + 5.7.4 Query Temporal Evolution of Entities. + + This operation allows querying the temporal evolution of Entities present in an NGSI-LD system. + It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query. + operationId: queryTemporal + parameters: + # Query params + - $ref: '#/components/parameters/Query.id' + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.idPattern' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.q' + - $ref: '#/components/parameters/Query.csf' + - $ref: '#/components/parameters/Query.geometry' + - $ref: '#/components/parameters/Query.georel' + - $ref: '#/components/parameters/Query.coordinates' + - $ref: '#/components/parameters/Query.geoproperty' + - $ref: '#/components/parameters/Query.timeproperty' + - $ref: '#/components/parameters/Query.timerel' + required: true + - $ref: '#/components/parameters/Query.timeAt' + required: true + - $ref: '#/components/parameters/Query.endTimeAt' + - $ref: '#/components/parameters/Query.lastN' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.aggrMethods' + - $ref: '#/components/parameters/Query.aggrPeriodDuration' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.options.temporal' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the query result as a list of temporal representation of Entities. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + '400': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/BadRequest' + /temporal/entities/{entityId}: + get: + tags: + - Temporal Context Information Consumption + summary: | + Temporal Representation of Entity retrieval by id + description: | + 5.7.3 Retrieve Temporal Evolution of an Entity. + + This operation allows retrieving the temporal evolution of an NGSI-LD Entity. + operationId: retrieveTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.timeproperty' + - $ref: '#/components/parameters/Query.timerel' + required: true + - $ref: '#/components/parameters/Query.timeAt' + required: true + - $ref: '#/components/parameters/Query.endTimeAt' + - $ref: '#/components/parameters/Query.lastN' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.aggrMethods' + - $ref: '#/components/parameters/Query.aggrPeriodDuration' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.options.temporal' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD temporal representation + of the target entity containing the selected Attributes. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Temporal Context Information Provision + summary: | + Temporal Representation of Entity deletion by id + description: | + 5.6.16 Delete Temporal Representation of an Entity. + + This operation allows deleting the Temporal Representation of an Entity. + operationId: deleteTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entities/{entityId}/attrs: + post: + tags: + - Temporal Context Information Provision + summary: | + Temporal Representation of Entity Attribute instance addition + description: | + 5.6.12 Append Entity Attributes. + + This operation allows modifying a Temporal Representation of an Entity by adding new Attribute instances. + operationId: appendAttrsTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + EntityTemporal Fragment containing a complete representation of the Attribute instances to be added. + $ref: '#/components/requestBodies/EntityTemporalFragment' + responses: + '204': + description: | + All the Attributes were added successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entities/{entityId}/attrs/{attrId}: + delete: + tags: + - Temporal Context Information Provision + summary: | + Attribute from Temporal Representation of Entity deletion + description: | + 5.6.13 Delete Attributes from Temporal Representation of an Entity. + + This operation allows deleting an NGSI-LD Entity's Attribute (Property or Relationship). + The Attribute itself and all its children shall be deleted. + operationId: deleteAttrsTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Query params + - $ref: '#/components/parameters/Query.deleteAll' + - $ref: '#/components/parameters/Query.datasetId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + The attribute was deleted successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entities/{entityId}/attrs/{attrId}/{instanceId}: + patch: + tags: + - Temporal Context Information Provision + summary: | + Attribute Instance update + description: | + 5.6.14 Partial Update Attribute instance in Temporal Representation of an Entity. + + This operation allows modifying a specific Attribute (Property or Relationship) instance, + identified by its instanceId, of a Temporal Representation of an Entity. + + This operation enables the correction of wrong information that could have been previously added + to the Temporal Representation of an Entity. + operationId: updateAttrsTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + - $ref: '#/components/parameters/Path.instanceId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Entity Fragment containing the elements of the attribute to be updated. + $ref: '#/components/requestBodies/EntityTemporalFragment' + responses: + '204': + description: | + The attribute was updated successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Temporal Context Information Provision + summary: | + Attribute Instance deletion by instance id + description: | + 5.6.15 Delete Attribute Instance from Temporal Representation of an Entity. + + This operation allows deleting one Attribute instance (Property or Relationship), + identified by its instanceId, of a Temporal Representation of an Entity. + The Attribute itself and all its child elements shall be deleted. This operation enables + the removal of individual Attribute instances that could have been previously added + to the Temporal Representation of an Entity. + operationId: deleteAttrInstanceTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + - $ref: '#/components/parameters/Path.instanceId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + The attribute instance was delete successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entityOperations/query: + post: + tags: + - Temporal Context Information Consumption + summary: | + Temporal Representation of Entity Query based on POST + description: | + 5.7.4 Query Temporal Evolution of Entities. + + This operation allows querying the temporal evolution of Entities present in an NGSI-LD system. + It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query. + operationId: temporalQueryBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Payload body in the request contains a JSON-LD object which represents the query to be performed. + $ref: '#/components/requestBodies/QueryTemporal' + responses: + '200': + description: | + A response body containing the query result as a list of Entities. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /types: + get: + tags: + - Context Information Consumption + summary: | + Retrieve available entity types + description: | + 5.7.5 Retrieve Available Entity Types. + + This operation allows retrieving a list of NGSI-LD entity types for which + entity instances exist within the NGSI-LD system. + operationId: retrieveTypes + parameters: + # Query params + - name: details + in: query + description: | + If true, then detailed entity type information represented as an array with + elements of the Entity Type data structure (clause 5.2.25) is to be returned. + style: form + explode: true + schema: + type: boolean + required: false + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the EntityTypeList + (clause 5.2.24) is to be returned, unless details=true is specified. + + If details=true is specified, a response body containing a JSON-LD array + with elements of the EntityType data structure (clause 5.2.25) is to be returned. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + oneOf: + - type: array + items: + $ref: '#/components/schemas/EntityTypeList' + - type: array + items: + $ref: '#/components/schemas/EntityType' + application/json+ld: + schema: + oneOf: + - allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - type: array + items: + $ref: '#/components/schemas/EntityTypeList' + - allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - type: array + items: + $ref: '#/components/schemas/EntityType' + '400': + $ref: '#/components/responses/BadRequest' + /types/{type}: + get: + tags: + - Context Information Consumption + summary: | + Details about available entity type + description: | + 5.7.7 Retrieve Available Entity Type information. + + This operation allows retrieving detailed entity type information about a specified NGSI-LD entity + type for which entity instances exist within the NGSI-LD system. The detailed representation includes + the type name (as short name if available in the provided @context), the count of available entity + instances and details about attributes that existing instances of this entity type have, including + their name (as short name if available in the provided @context) and a list of types the attribute + can have (e.g. Property, Relationship or GeoProperty). + operationId: retrieveTypeInfo + parameters: + # Path params + - $ref: '#/components/parameters/Path.type' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of + the detailed information about the available entity type. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/EntityTypeInfo' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/EntityTypeInfo' + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /attributes: + get: + tags: + - Context Information Consumption + summary: | + Retrieve Available Attributes + description: | + 5.7.8 Retrieve Available attributes. + + This operation allows retrieving a list of NGSI-LD attributes that belong to + entity instances existing within the NGSI- LD system. + operationId: retrieveAttributes + parameters: + # Query params + - name: details + in: query + description: | + If true, then detailed attribute information represented as an array + with elements of the Attribute data structure (clause 5.2.28) is to be returned. + style: form + explode: true + schema: + type: boolean + required: false + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the AttributeList + (clause 5.2.27) is to be returned, unless details=true is specified. + + If details=true is specified, a response body containing a JSON-LD array + with elements of the Attribute data structure (clause 5.2.28) is to be returned. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/AttributeList' + - type: array + items: + $ref: '#/components/schemas/Attribute' + application/json+ld: + schema: + oneOf: + - allOf: + - $ref: '#/components/schemas/AttributeList' + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - allOf: + - type: array + items: + $ref: '#/components/schemas/Attribute' + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + '400': + $ref: '#/components/responses/BadRequest' + /attributes/{attrId}: + get: + tags: + - Context Information Consumption + summary: | + Retrieve Available Attribute Information + description: | + 5.7.10 Retrieve Available Attribute information. + + This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute + that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes + the attribute name (as short name if available in the provided @context) and the type names + for which entity instances exist that have the respective attribute, a count of available + attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty). + operationId: retrieveAttrInfo + parameters: + # Path params + - $ref: '#/components/parameters/Path.attrId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of + the detailed information about the available attribute. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/Attribute' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Attribute' + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /jsonldContexts: + post: + tags: + - JSON-LD Context API + summary: | + Add a user @context to the internal cache + description: | + 5.13.2 Add @context. + + With this operation, a client can ask the Broker to store the full content + of a specific @context, by giving it to the Broker. + operationId: createContext + requestBody: + description: | + Payload body in the request contains a JSON object that has a root node named @context, + which represents a JSON-LD "local" context. + required: true + content: + application/json: + schema: + type: object + application/json+ld: + schema: + type: object + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains the + local URI of the added @context. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + get: + tags: + - JSON-LD Context API + summary: | + List all cached @contexts + description: | + 5.13.3 List @contexts. + + With this operation a client can obtain a list of URLs that represent all of the @contexts + stored in the local context store of the Broker. Each URL can be used to download the + corresponding @context, and, in case the @context's kind is "Cached", it shall be + the original URL the Broker downloaded the @context from. + + In case a "details" flag is set to true, the client obtains a list of JSON objects, + each representing information (metadata) about an @context currently stored by the Broker. + Each JSON object contains information about the @context's original URL (if any), its + local identifier in the Broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"), + its creation timestamp, its expiry date (if "Cached"), and additional optional information. + operationId: listContexts + parameters: + # Query params + - $ref: '#/components/parameters/Query.details' + - $ref: '#/components/parameters/Query.kind' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing a list of URLs or a list of JSON Objects, as defined in clause 5.13.3.5, + representing metadata about stored @contexts. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + # TODO: Output data described in 5.13.3.5, but not formally defined in tables. + application/json: + schema: + oneOf: + - type: array + items: + type: string + format: uri + - type: array + items: + type: object + application/json+ld: + schema: + oneOf: + - type: array + items: + allOf: + - type: string + format: uri + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - type: array + items: + allOf: + - type: object + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + '400': + $ref: '#/components/responses/BadRequest' + /jsonldContexts/{contextId}: + get: + tags: + - JSON-LD Context API + summary: | + Serve one specific user @context + description: | + 5.13.4 Serve @context. + + With this operation a client can obtain the full content of a specific @context + (only for @contexts of kind "Hosted" or "ImplicitlyCreated"), which is currently + stored in the Broker's internal storage, or its metadata (for all kinds of stored @contexts). + operationId: retrieveContext + parameters: + # Path params + - $ref: '#/components/parameters/Path.contextId' + # Query params + - $ref: '#/components/parameters/Query.details' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + 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". + If the parameter details is True, response body contains a JSON object as defined + in clause 5.13.4.5, which metadata of a JSON-LD "local context". + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: object + application/json+ld: + schema: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - type: object + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/Unprocessable' + delete: + tags: + - JSON-LD Context API + summary: | + Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it + description: | + 5.13.5 Delete and Reload @context + + With this operation, a client supplies a local identifier to the Broker, indicating + a stored @context, that the Broker shall remove from its storage. For @contexts of + kind "Cached" this can also be the original URL the Broker downloaded the @context from. + If the entry in the local storage that corresponds to the identifier is itself + an array of @contexts, this operation will not delete the children, + i.e. the @contexts in the array, but just the entry. + operationId: deleteContext + parameters: + # Path params + - $ref: '#/components/parameters/Path.contextId' + # Query params + - $ref: '#/components/parameters/Query.reload' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '503': + $ref: '#/components/responses/ServiceUnavailable' + +components: + headers: + Location: + description: | + Contains the resource URI of the created entity resource. + schema: + type: string + NGSILD-Results-Count: + description: | + 6.3.13 Counting number of results + schema: + type: integer + NGSILD-Tenant: + description: | + 6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted. + schema: + type: string + NGSILD-Warning: + description: | + 6.3.17 Distributed Operations Caching and Timeout Behaviour + schema: + type: string + enum: + - '110 - Response is Stale' + - '111 - Revalidation Failed' + - '199 - Miscellaneous Warning' + - '299 - Miscellaneous Persistent Warning' + required: false + parameters: + Headers.Link: + name: Link + in: header + description: | + 6.3.5 JSON-LD @context resolution + + In summary, from a developer's perspective, for POST, PATCH and PUT operations, + if MIME type is "application/ld+json", then the associated @context shall be provided + only as part of the request payload body. Likewise, if MIME type is "application/json", + then the associated @context shall be provided only by using the JSON- LD Link header. + No mixes are allowed, i.e. mixing options shall result in HTTP response errors. + Implementations should provide descriptive error messages when these situations arise. + + In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header. + explode: true + schema: + type: string + format: uri + Headers.ngsildCount: + name: NGSILD-Results-Count + in: header + description: | + 6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned. + explode: true + schema: + type: integer + Headers.ngsildTenant: + name: NGSILD-Tenant + in: header + description: | + 6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted. + explode: true + schema: + type: string + Path.attrId: + name: attrId + in: path + description: | + Name of the attribute for which detailed information is to be retrieved. + The Fully Qualified Name (FQN) as well as the short name can be used, + given that the latter is part of the JSON-LD @context provided. + schema: + type: string + required: true + Path.contextId: + name: contextId + in: path + description: | + Local identifier of the @context to be managed (served or deleted). For @contexts of kind "Cached" + this can also be the original URL the Broker downloaded the @context from. + schema: + type: string + required: true + Path.entityId: + name: entityId + in: path + description: Id (URI) of the entity to be retrieved. + schema: + type: string + format: uri + required: true + Path.instanceId: + name: instanceId + in: path + description: Id (URI) identifying a particular Attribute instance. + schema: + type: string + format: uri + required: true + Path.registrationId: + name: registrationId + in: path + description: Id (URI) of the context source registration. + schema: + type: string + format: uri + required: true + Path.subscriptionId: + name: subscriptionId + in: path + description: Id (URI) of the concerned subscription. + schema: + type: string + format: uri + required: true + Path.type: + name: type + in: path + description: | + Name of the entity type for which detailed information is to be retrieved. + The Fully Qualified Name (FQN) as well as the short name can be used, + given that the latter is part of the JSON-LD @context provided. + schema: + type: string + required: true + Query.aggrMethods: + name: aggrMethods + in: query + description: | + 4.5.19.1 Aggregated Temporal Representation of an Entity. + + Comma separated list of aggregation methods. + + Only applicable if aggregatedValues is present in the options parameter. + style: form + explode: false + schema: + type: string + enum: + - 'totalCount' + - 'distinctCount' + - 'sum' + - 'avg' + - 'min' + - 'max' + - 'stddev' + - 'sumsq' + required: false + Query.aggrPeriodDuration: + name: aggrPeriodDuration + in: query + description: | + If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning + the whole time range specified by the temporal query. + + Only applicable if aggregatedValues is present in the options parameter. + style: form + explode: false + schema: + type: string + required: false + Query.attrs: + name: attrs + in: query + description: | + List of Attributes to be matched by the Entity and included in the response. If the Entity does not + have any of the Attributes in attrs, then a 404 Not Found shall be retrieved. If attrs is not + specified, no matching is performed and all Attributes related to the Entity shall be retrieved. + style: form + explode: false + schema: + type: array + items: + type: string + format: uri + required: false + Query.coordinates: + name: coordinates + in: query + description: | + Coordinates serialized as a string as per clause 4.10. It is part of geoquery. + It shall be one if geometry or georel are present. + style: form + explode: true + schema: + oneOf: + - $ref: '#/components/schemas/Geometry.position' + - $ref: '#/components/schemas/Geometry.positionArray' + - $ref: '#/components/schemas/Geometry.lineString' + - $ref: '#/components/schemas/Geometry.polygon' + required: false + Query.count: + name: count + in: query + description: | + 6.3.13 Counting number of results. If true, then a special HTTP header (NGSILD-Results-Count) is set in + the response. Regardless of how many entities are actually returned (maybe due to the "limit" URI parameter), + the total number of matching results (e.g. number of Entities) is returned. + style: form + explode: true + schema: + type: boolean + required: false + Query.csf: + name: csf + in: query + description: Context Source filter as per clause 4.9. + style: form + explode: true + schema: + type: string + required: false + Query.datasetId: + name: datasetId + in: query + description: | + Specifies the datasetId of the dataset to be deleted. + style: form + explode: true + schema: + type: string + format: uri + required: false + Query.details: + name: details + in: query + description: Whether a list of URLs or a more detailed list of JSON Objects is requested. + style: form + explode: true + schema: + type: boolean + required: false + Query.deleteAll: + name: deleteAll + in: query + description: | + If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified + by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, + the default Attribute instance is deleted. + style: form + explode: true + schema: + type: boolean + required: false + Query.endTimeAt: + name: endTimeAt + in: query + description: | + It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between". + String representing the endTimeAt parameter as defined by clause 4.11. + style: form + explode: true + schema: + type: string + format: date-time + required: false + Query.id: + name: id + in: query + description: List of entity ids to be retrieved. + style: form + explode: false + schema: + type: array + items: + type: string + format: uri + required: false + Query.idPattern: + name: idPattern + in: query + description: Regular expression that shall be matched by entity ids. + style: form + explode: true + schema: + type: string + format: pattern + required: false + Query.geometryProperty: + name: geometryProperty + in: query + description: | + In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use + for the toplevel geometry field. + style: form + explode: true + schema: + type: string + required: false + Query.geometry: + name: geometry + in: query + description: | + Geometry as per clause 4.10. It is part of geoquery. It shall be one if geometry or georel are present. + style: form + explode: true + schema: + type: string + enum: + - Point + - MultiPoint + - LineString + - MultiLineString + - Polygon + - MultiPolygon + required: false + Query.geoproperty: + name: geoproperty + in: query + description: | + The name of the Property that contains the geospatial data that will be used to resolve the geoquery. + By default, will be location (see clause 4.7). It shall be ignored unless a geoquery is present. + style: form + explode: true + schema: + type: string + required: false + Query.georel: + name: georel + in: query + description: | + Geo relationship as per clause 4.10. It is part of geoquery. It shall be one if + geometry or georel are present. + style: form + explode: true + schema: + oneOf: + - type: string + enum: + - equals + - disjoint + - intersects + - within + - contains + - overlaps + - type: string + pattern: ^near;((maxDistance==\\d+)|(minDistance==\\d+))$ + required: false + Query.kind: + name: kind + in: query + description: | + Can be either "Cached", "Hosted", or "ImplicitlyCreated". + style: form + explode: true + schema: + type: string + enum: + - Cached + - Hosted + - ImplicitlyCreated + required: false + Query.lang: + name: lang + in: query + description: | + It is used to reduce languageMaps to a string or string array property in a single preferred language. + style: form + explode: true + schema: + type: string + required: false + Query.lastN: + name: lastN + in: query + description: | + Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. + style: form + explode: true + schema: + type: integer + minimum: 0 + required: false + Query.limit: + name: limit + in: query + description: | + 6.3.10 Pagination behaviour. It defines the limit to the number of NGSI-LD Elements that shall be retrieved + at a maximum as mandated by clause 5.5.9. The value 0 is only allowed in combination with + the count URI parameter. + style: form + explode: true + schema: + type: integer + minimum: 0 + required: false + Query.local: + name: local + in: query + description: | + 6.3.18 Limiting Distributed Operations. If local=true then no Context Source Registrations shall be + considered as matching to avoid cascading distributed operations (see clause 4.3.6.4). + style: form + explode: true + schema: + type: boolean + required: false + Query.observedAt: + name: observedAt + in: query + description: | + When a merge operation applies to a pre-existing Attribute which previously contained an "observedAt" + sub-attribute, the value held in this query parameter shall be used if no specific "observedAt" + sub-Attribute is found in the payload body. + schema: + type: string + format: date-time + required: false + Query.options.entities: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + anyOf: + - $ref: '#/components/schemas/options.representation' + - $ref: '#/components/schemas/options.sysAttrs' + required: false + Query.options.noOverwrite: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.noOverwrite' + required: false + Query.options.sysAttrs: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.sysAttrs' + required: false + Query.options.temporal: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.temporal' + required: false + Query.options.upsert: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.upsert' + required: false + Query.q: + name: q + in: query + description: | + Query as per clause 4.9. + style: form + explode: true + schema: + type: string + required: false + Query.reload: + name: reload + in: query + description: | + Indicates to perform a download and replace of the @context, as specified in clause 5.13.5.4. + style: form + explode: true + schema: + type: boolean + required: false + Query.scopeQ: + name: scopeQ + in: query + description: | + Scope query (see clause 4.19). + style: form + explode: true + schema: + type: string + required: false + Query.timeAt: + name: timeAt + in: query + description: | + It shall be a DateTime. Cardinality shall be 1 if timerel is present. + String representing the timeAt parameter as defined by clause 4.11. + style: form + explode: true + schema: + type: string + format: date-time + required: false + Query.timeproperty: + name: timeproperty + in: query + description: | + Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". + If not specified, the default is "observedAt". (See clause 4.8) + style: form + explode: true + schema: + type: string + enum: + - observedAt + - createdAt + - modifiedAt + - deletedAt + required: false + Query.timerel: + name: timerel + in: query + description: | + Allowed values: "before", "after", "between" + style: form + explode: true + schema: + type: string + enum: + - before + - after + - between + required: false + Query.type: + name: type + in: query + description: | + Selection of Entity Types as per clause 4.17. + style: form + explode: true + schema: + type: string + required: false + requestBodies: + AttributeFragment: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + application/json+ld: + schema: + allOf: + - oneOf: + - $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + EntityTemporal: + content: + application/json: + schema: + $ref: '#/components/schemas/EntityTemporal' + required: + - id + - type + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - id + - type + - '@context' + EntityTemporalFragment: + content: + application/json: + schema: + $ref: '#/components/schemas/EntityTemporal' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + Query: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Query' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + QueryTemporal: + content: + application/json: + schema: + $ref: '#/components/schemas/Query.temporal' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Query.temporal' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + Subscription: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - type + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - type + - '@context' + SubscriptionFragment: + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + application/json+ld: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - required: + - '@context' + schemas: + AnyValue: + description: Any JSON value as defined by IETF RFC 8259. + ### + # Beginning of Options parameters + # + options.noOverwrite: + description: Indicates that no attribute overwrite shall be performed. + type: string + enum: + - noOverwrite + options.representation: + description: | + 6.3.7 Representation of Entities. When its value includes the keyword "normalized", a normalized + representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned + in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2 and 4.5.18.2. + + When its value includes the keyword "concise", a concise lossless representation of Entities shall + be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as + defined in clauses 4.5.2.3, 4.5.3.3 and 4.5.18.3. In this case the broker will return data in the + most concise lossless representation possible, for example removing all Attribute "type" members. + + When its value includes the keyword "keyValues" (or "simplified" as a synonym), a simplified + representation of Entities shall be provided as defined by clause 4.5.4. + + If the Accept Header is set to "application/geo+json" the response will be in simplified GeoJSON + format as defined by clause 4.5.17. + type: string + enum: + - normalized + - concise + - keyValues + options.sysAttrs: + description: 6.3.11 Including system generated attributes. + type: string + enum: + - sysAttrs + options.temporal: + description: | + 6.3.12 Simplified or aggregated temporal representation of entities. + + When its value includes the keyword "temporalValues", a simplified temporal representation of + entities shall be provided as defined by clause 4.5.8. + + When its value includes the keyword "aggregatedValues", an aggregated temporal representation of + entities shall be provided as defined by clause 4.5.19. + + Only one of the two keywords can be present in the values of the parameter. + type: string + enum: + - temporalValues + - aggregatedValues + options.upsert: + description: | + 6.15.3 Upsert configuration. + + "replace". Indicates that all the existing Entity content shall be replaced (default mode); + + "update". Indicates that existing Entity content shall be updated. + type: string + enum: + - replace + - update + # + # End of Options parameters + ### + ### + # + # Beginning of 4.8 Temporal Properties + # + CreatedAt: + description: | + Is defined as the temporal Property at which the Entity, Property or + Relationship was entered into an NGSI-LD system. + type: string + format: date-time + ModifiedAt: + description: | + Is defined as the temporal Property at which the Entity, Property or Relationship + was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value. + type: string + format: date-time + DeletedAt: + description: | + Is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system. + + Entity deletion timestamp. See clause 4.8 It is only used in notifications reporting deletions and in the + Temporal Representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8) + and LanguageProperties (clause 5.2.32). + type: string + format: date-time + ObservedAt: + description: | + Is defined as the temporal Property at which a certain Property or Relationship became valid or was observed. + For example, a temperature Value was measured by the sensor at this point in time. + type: string + format: date-time + # + # End of 4.8 Temporal Properties + ### + + Attribute: + description: | + 5.2.28 This type represents the data needed to define the attribute information. + type: object + properties: + id: + description: | + Full URI of attribute name. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - Attribute + attributeName: + description: | + Name of the attribute, short name if contained in @context. + type: string + attributeCount: + description: | + Number of attribute instances with this attribute name. + type: number + attributeTypes: + description: | + List of attribute types (e.g. Property, Relationship, GeoProperty) for which + entity instances exist, which contain an attribute with this name. + type: array + items: + type: string + typeNames: + description: | + List of entity type names for which entity instances exist containing + attributes that have the respective name. + type: array + items: + type: string + required: + - id + - type + - attributeName + AttributeList: + description: | + 5.2.27 This type represents the data needed to define the attribute + list representation as mandated by clause 4.5.13. + type: object + properties: + id: + description: | + Unique identifier for the attribute list. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - AttributeList + attributeList: + description: | + List containing the attribute names. + type: array + items: + type: string + required: + - id + - type + - attributeList + BatchEntityError: + description: | + 5.2.17 represents an error raised (associated to a particular Entity) during + the execution of a batch or distributed operation. + type: object + properties: + entityId: + description: | + Entity Id corresponding to the Entity in error. + type: string + format: uri + registrationId: + description: | + Registration Id corresponding to a failed distributed operation (optional). + type: string + format: uri + error: + description: | + One instance per Entity in error. + $ref: '#/components/schemas/ProblemDetails' + required: + - entityId + - error + BatchOperationResult: + description: | + 5.2.16 represents the result of a batch operation. + type: object + properties: + success: + description: | + Array of Entity Ids corresponding to the Entities that were successfully + treated by the concerned operation. + type: array + items: + type: string + format: uri + errors: + description: | + One array item per Entity in error. + type: array + items: + $ref: '#/components/schemas/BatchEntityError' + required: + - success + - error + CsourceNotification: + description: | + 5.3.2 This datatype represents the parameters that allow building a Context Source Notification + to be sent to a subscriber. + type: object + properties: + id: + description: | + Csource notification identifier (JSON-LD @id). + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - CsourceNotification + subscriptionId: + description: | + Identifier of the subscription that originated the notification. + type: string + format: uri + notifiedAt: + description: | + Timestamp corresponding to the instant when the notification was generated by the system. + type: string + format: date-time + data: + description: | + The content of the notification as NGSI-LD entities. See clause 5.2.4. + type: array + items: + $ref: '#/components/schemas/CsourceRegistration' + readOnly: true + triggerReason: + description: | + Indicates whether the Csources in the CsourceRegistration.Input(s) in data are newly matching + (initial notification or creation), have been updated (but still match) or do not match any longer. + + • "newlyMatching" - describes the case that the notified Context Source Registration(s) newly + match(es) the identified subscription. This value is used in the first notification and + whenever a new Context Source Registration matching the Subscription has been registered, + or an existing Context Source Registration that did not match before has been updated + in such a way that it matches now. + + • "updated" - describes the case that the notified Context Source Registration that + was part of a previous notification has been updated, but still matches the Subscription. + + • "noLongerMatching" - describes the case that the notified Context Source Registration + that was part of a previous notification no longer matches the Subscription, i.e. as a result of + an update or because it was deleted. + type: string + enum: + - newlyMatching + - updated + - noLongerMatching + required: + - id + - type + - subscriptionId + - notifiedAt + - data + - triggerReason + CsourceRegistration: + description: | + 5.2.9 represents the data needed to register a new Context Source. + type: object + properties: + id: + description: | + Unique registration identifier. (JSON-LD @id). There may be multiple registrations per + Context Source, i.e. the id is unique per registration. + type: string + format: uri + type: + description: | + JSON-LD @type Use reserved type for identifying Context Source Registration. + type: string + enum: + - ContextSourceRegistration + registrationName: + description: | + A name given to this Context Source Registration. + type: string + minLength: 1 + description: + description: | + A description of this Context Source Registration. + type: string + minLength: 1 + information: + description: | + Describes the Entities, Properties and Relationships for which the + Context Source may be able to provide information. + type: array + items: + $ref: '#/components/schemas/RegistrationInfo' + minItems: 1 + tenant: + description: | + Identifies the tenant that has to be specified in all requests to the Context Source that + are related to the information registered in this Context Source Registration. + If not present, the default tenant is assumed. Should only be present in systems supporting multi-tenancy. + type: string + format: uri + observationInterval: + description: | + If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity + information is also provided, a separate Context Registration is needed for this purpose). + The observationInterval specifies the time interval for which the Context Source can provide + Entity information as specified by the observedAt Temporal Property. + A temporal query based on the observedAt Temporal Property, which is the default, + is matched against the observationInterval for overlap. + $ref: '#/components/schemas/TimeInterval' + managementInterval: + description: | + If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity + information is also provided, a separate Context Registration is needed for this purpose). + The managementInterval specifies the time interval for which the Context Source can provide Entity + information as specified by the createdAt, modifiedAt and deletedAt Temporal Properties. + A temporal query based on the createdAt, modifiedAt or deletedAt Temporal Property is matched + against the managementInterval for overlap. + $ref: '#/components/schemas/TimeInterval' + location: + description: | + Location for which the Context Source may be able to provide information. + $ref: '#/components/schemas/Geometry' + observationSpace: + $ref: '#/components/schemas/Geometry' + operationSpace: + $ref: '#/components/schemas/Geometry' + expiresAt: + description: | + Provides an expiration date. When passed the Context Source Registration + will become invalid and the Context Source might no longer be available. + type: string + format: date-time + endpoint: + description: | + Endpoint expressed as dereferenceable URI through which the Context Source exposes its NGSI-LD interface. + type: string + format: uri + contextSourceInfo: + description: | + Generic {key, value} array to convey optional information to provide + when contacting the registered Context Source. + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + scope: + description: | + Scopes (see clause 4.18) for which the Context Source has Entities. + oneOf: + - type: string + - type: array + items: + type: string + mode: + description: | + The definition of the mode of distributed operation (see clause 4.3.6) + supported by the registered Context Source. + type: string + enum: + - inclusive + - exclusive + - redirect + - auxiliary + operations: + description: | + The definition limited subset of API operations supported by the registered Context Source. + + If undefined, the default set of operations is "federationOps" (see clause 4.20). + type: array + items: + type: string + refreshRate: + description: | + An indication of the likely period of time to elapse between updates at this registered endpoint. + Brokers may optionally use this information to help implement caching. + type: string + management: + description: | + Holds additional optional registration management information that can be used + to limit unnecessary distributed operation requests. + $ref: '#/components/schemas/RegistrationManagementInfo' + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + status: + description: | + Read-only. Status of the Registration. It shall be "ok" if the last attempt to perform a distributed + operation succeeded. It shall be "failed" if the last attempt to perform a distributed operation failed. + type: string + enum: + - ok + - failed + readOnly: true + timesSent: + description: | + Number of times that the registration triggered a distributed operation, including failed attempts. + type: number + minimum: 0 + readOnly: true + timesFailed: + description: Number of times that the registration triggered a distributed operation request that failed. + type: number + minimum: 0 + readOnly: true + lastSuccess: + description: | + Timestamp corresponding to the instant when the last successfully distributed operation was sent. + Created on first successful operation. + type: string + format: date-time + readOnly: true + lastFailure: + description: | + Timestamp corresponding to the instant when the last distributed operation resulting in + a failure (for instance, in the HTTP binding, an HTTP response code other than 2xx) was returned. + type: string + format: date-time + readOnly: true + additionalProperties: + $ref: '#/components/schemas/AnyValue' + DateTimeValue: + description: | + Date representation as mandated by C.6 "Date Representation" + type: object + properties: + '@type': + type: string + enum: + - DateTime + default: DateTime + '@value': + type: string + format: date-time + required: + - '@type' + - '@value' + Endpoint: + description: | + 5.2.15 represents the parameters that are required in order to define an endpoint for notifications. + type: object + properties: + uri: + description: | + URI which conveys the endpoint which will receive the notification. + type: string + format: uri + accept: + description: | + Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). + If not present, default is "application/json". + type: string + enum: + - application/json + - application/ld+json + - application/geo+json + timeout: + description: | + Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. + The NGSI-LD system can override this value. This only applies if the binding + protocol always returns a response. + type: number + cooldown: + description: | + Once a failure has occurred, minimum period of time in milliseconds which shall elapse before + attempting to make a subsequent notification to the same endpoint after failure. + If requests are received before the cooldown period has expired, no notification is sent. + type: number + receiverInfo: + description: | + Generic {key, value} array to convey optional information to the receiver. + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + notifierInfo: + description: | + Generic {key, value} array to set up the communication channel. + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + required: + - uri + Entity: + description: | + NGSI-LD Entity (see 5.4). + type: object + properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. + oneOf: + - type: string + - type: array + items: + type: string + scope: + description: | + Scope. + oneOf: + - type: string + - type: array + items: + type: string + location: + description: | + Default geospatial Property of an entity. See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + observationSpace: + $ref: '#/components/schemas/GeoProperty' + operationSpace: + $ref: '#/components/schemas/GeoProperty' + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + EntityInfo: + description: | + 5.2.8 represents what Entities, Entity Types or group of Entity ids + (as a regular expression pattern mandated by IEEE 1003.2TM [11]) can be provided (by Context Sources). + type: object + properties: + id: + description: | + Entity identifier. + type: string + format: uri + idPattern: + description: | + A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. + type: string + format: pattern + type: + description: | + Entity Type (or JSON array, in case of Entities with multiple Entity Types). + oneOf: + - type: string + - type: array + items: + type: string + required: + - type + EntitySelector: + description: | + 5.2.33 This type selects which entity or group of entities are queried or subscribed to by Context Consumers. + `id` takes precedence over `idPattern`. + type: object + properties: + id: + description: | + Entity identifier. + type: string + format: uri + idPattern: + description: | + A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. + type: string + type: + description: | + Selector of Entity Type(s). + type: string + required: + - type + EntityTemporal: + description: | + 5.2.20 This is the same data type as mandated by clause 5.2.4 with the only deviation that + the representation of Properties and Relationships shall be the temporal one + (arrays of (Property or Relationship) instances represented by JSON-LD objects) + as defined in clauses 4.5.7 and 4.5.8. Alternatively it is possible to specify + the EntityTemporal by using the "Simplified Temporal Representation of an Entity", + as defined in clause 4.5.9. + properties: + location: + description: | + Default geospatial Property of an entity. See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + observationSpace: + $ref: '#/components/schemas/GeoProperty' + operationSpace: + $ref: '#/components/schemas/GeoProperty' + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + additionalProperties: + oneOf: + - type: array + items: + $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/GeoProperty' + - type: array + items: + $ref: '#/components/schemas/LanguageProperty' + EntityType: + description: | + 5.2.25 This type represents the data needed to define the elements of the detailed + entity type list representation as mandated by clause 4.5.11. + type: object + properties: + id: + description: | + Fully Qualified Name (FQN) of the entity type being described. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - EntityType + typeName: + description: | + Name of the entity type, short name if contained in @context. + type: string + attributeNames: + description: | + List containing the names of attributes that instances of the entity type can have. + type: array + items: + type: string + required: + - id + - type + - typeName + - attributeNames + EntityTypeInfo: + description: | + 5.2.26 This type represents the data needed to define the detailed entity type + information representation as mandated by clause 4.5.12. + type: object + properties: + id: + description: | + Fully Qualified Name (FQN) of the entity type being described. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - EntityTypeInfo + typeName: + description: | + Name of the entity type, short name if contained in @context. + type: string + entityCount: + description: | + Number of entity instances of this entity type. + type: number + attributeDetails: + description: | + List of attributes that entity instances with the specified entity type can have. + type: array + items: + $ref: '#/components/schemas/Attribute' + required: + - id + - type + - typeName + - entityCount + - attributeDetails + EntityTypeList: + description: | + 5.2.24 This type represents the data needed to define the entity type + list representation as mandated by clause 4.5.10. + type: object + properties: + id: + description: | + Unique identifier for the entity type list. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - EntityTypeList + typeList: + description: | + List containing the entity type names. + type: array + items: + type: string + required: + - id + - type + - typeList + Feature: + description: | + 5.2.29 This data type represents a spatially bounded Entity in GeoJSON format, as mandated by IETF RFC 7946. + type: object + properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + GeoJSON Type. + type: string + enum: + - Feature + geometry: + description: | + Null if no matching GeoProperty. + $ref: '#/components/schemas/Geometry' + properties: + description: | + List of attributes as mandated by clause 5.2.31. + $ref: '#/components/schemas/FeatureProperties' + '@context': + description: | + JSON-LD @context. This field is only present if requested in the payload by + the HTTP Prefer Header (IETF RFC 724). + $ref: '#/components/schemas/LdContext' + required: + - id + - type + - geometry + - properties + FeatureCollection: + description: | + 5.2.30 This data type represents a list of spatially bounded + Entities in GeoJSON format, as mandated by IETF RFC 7946. + type: object + properties: + type: + description: | + GeoJSON Type. + type: string + enum: + - FeatureCollection + features: + description: | + In the case that no matches are found, "features" will be an empty array. + type: array + items: + $ref: '#/components/schemas/Feature' + '@context': + description: | + JSON-LD @context. This field is only present if requested in the payload + by the HTTP Prefer Header (IETF RFC 724). + $ref: '#/components/schemas/LdContext' + required: + - type + FeatureProperties: + description: | + 5.2.31 This data type represents the type and the associated attributes + (Properties and Relationships) of an Entity in GeoJSON format. + type: object + properties: + type: + description: | + Entity Type (or JSON array, in case of Entities with multiple Entity Types). + Both short hand string (type name) or URI are allowed. + oneOf: + - type: string + - type: array + items: + type: string + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - type: array + items: + $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - type: array + items: + $ref: '#/components/schemas/LanguageProperty' + required: + - type + ###### + # Geometry schemas (BEGIN) + # + Geometry.position: + description: | + A single position. + type: array + minItems: 2 + maxItems: 2 + items: + type: number + additionalProperties: false + Geometry.positionArray: + description: | + An array of positions. + type: array + items: + $ref: '#/components/schemas/Geometry.position' + Geometry.lineString: + description: | + An array of two or more positions. + allOf: + - $ref: '#/components/schemas/Geometry.positionArray' + - minItems: 2 + Geometry.linearRing: + description: | + An array of four positions where the first equals the last. + allOf: + - $ref: '#/components/schemas/Geometry.positionArray' + - minItems: 4 + Geometry.polygon: + description: | + An array of linear rings. + type: array + items: + $ref: '#/components/schemas/Geometry.linearRing' + Geometry.Point: + type: object + properties: + type: + type: string + enum: + - Point + coordinates: + $ref: '#/components/schemas/Geometry.position' + Geometry.MultiPoint: + type: object + properties: + type: + type: string + enum: + - MultiPoint + coordinates: + $ref: '#/components/schemas/Geometry.positionArray' + Geometry.Polygon: + type: object + properties: + type: + type: string + enum: + - Polygon + coordinates: + $ref: '#/components/schemas/Geometry.polygon' + Geometry.LineString: + type: object + properties: + type: + type: string + enum: + - LineString + coordinates: + $ref: '#/components/schemas/Geometry.lineString' + Geometry.MultiLineString: + type: object + properties: + type: + type: string + enum: + - MultiLineString + coordinates: + type: array + items: + $ref: '#/components/schemas/Geometry.lineString' + Geometry.MultiPolygon: + type: object + properties: + type: + type: string + enum: + - MultiPolygon + coordinates: + type: array + items: + $ref: '#/components/schemas/Geometry.lineString' + Geometry: + description: | + A valid GeoJSON geometry object. + oneOf: + - $ref: '#/components/schemas/Geometry.Point' + - $ref: '#/components/schemas/Geometry.MultiPoint' + - $ref: '#/components/schemas/Geometry.Polygon' + - $ref: '#/components/schemas/Geometry.LineString' + - $ref: '#/components/schemas/Geometry.MultiLineString' + - $ref: '#/components/schemas/Geometry.MultiPolygon' + # + # Geometry schemas (END) + ###### + GeoProperty: + description: | + 5.2.7 NGSI-LD GeoProperty. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - GeoProperty + default: GeoProperty + value: + $ref: '#/components/schemas/Geometry' + observedAt: + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + GeoQuery: + description: | + 5.2.13 represents a geoquery used for Subscriptions. + type: object + properties: + geometry: + description: | + Type of the reference geometry. + type: string + coordinates: + description: | + Coordinates of the reference geometry. For the sake of JSON-LD compatibility. + It can be encoded as a string as described in clause 4.7.1. + # To be checked + oneOf: + - type: string + - type: array + items: + type: object + georel: + description: | + Geo-relationship (near, within, etc.). + type: string + geoproperty: + description: | + Specifies the GeoProperty to which the GeoQuery is to be applied. + If not present, the default GeoProperty is location. + type: string + required: + - geometry + - coordinates + - georel + KeyValuePair: + description: | + 5.2.22 represents the optional information that is required when contacting an endpoint for notifications. + type: object + properties: + key: + description: | + The key of the key/value pair. + type: string + value: + description: | + The value of the key/value pair. + type: string + required: + - key + - value + LanguageProperty: + description: | + 5.2.32 NGSI-LD LanguageProperty. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - LanguageProperty + default: LanguageProperty + languageMap: + description: | + String Property Values defined in multiple natural languages. + type: object + observedAt: + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + previousLanguageMap: + description: | + Previous Language Property languageMap. Only used in notifications. + type: object + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + LdContext: + description: | + 5.2.3 JSON-LD @context + + When encoding NGSI-LD Entities, Context Source Registrations, Subscriptions and Notifications, + as pure JSON-LD (MIME type "application/ld+json"), a proper @context shall be included + as a special member of the corresponding JSON-LD Object. + oneOf: + - type: string + format: uri + - type: object + - type: array + items: + oneOf: + - type: string + format: uri + - type: object + NotUpdatedDetails: + description: | + 5.2.19 represents additional information provided by an implementation + when an Attribute update did not happen. + type: object + properties: + attributeName: + description: | + Attribute name. + type: string + reason: + description: | + Reason for not having changed such Attribute. + type: string + registrationId: + description: | + Registration Id corresponding to a failed distributed operation (optional). + type: string + format: uri + required: + - attributeName + - reason + Notification: + description: | + 5.3.1 This datatype represents the parameters that allow building a notification to be sent to a subscriber. + type: object + properties: + id: + description: | + Notification identifier (JSON-LD @id). It shall be automatically generated by the implementation. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - Notification + subscriptionId: + description: | + Identifier of the subscription that originated the notification. + type: string + format: uri + notifiedAt: + description: | + Timestamp corresponding to the instant when the notification was generated by the system. + type: string + format: date-time + data: + description: | + The content of the notification as NGSI-LD Entities. See clause 5.2.4. + + If the notification has been triggered from a Subscription that has the notification. + endpoint.accept field set to application/geo+json then data is returned as a FeatureCollection. + In this case, if the notification.endpoint.rece iverInfo contains the key "Prefer" and + it is set to the value "body=json", then the FeatureCollection will not contain + an @context field. + + If endpoint.accept is not set or holds another value then Entity[] is returned. + oneOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - $ref: '#/components/schemas/FeatureCollection' + required: + - id + - type + - subscriptionId + - notifiedAt + - data + NotificationParams: + description: | + 5.2.14 represents the parameters that allow to convey the details of a notification. + type: object + properties: + attributes: + description: | + Entity Attribute Names (Properties or Relationships) to be included in the notification payload body. + If undefined it will mean all Attributes. + type: array + items: + type: string + minItems: 1 + sysAttrs: + description: | + If true, the system generated attributes createdAt and modifiedAt are included in + the response payload body, in the case of a deletion also deletedAt. + type: boolean + format: + description: | + Conveys the representation format of the entities delivered at notification time. + By default, it will be in the normalized format. + type: string + enum: + - normalized + - concise + - keyValues + showChanges: + description: | + If true the previous value (previousValue) of Properties or languageMap (previousLanguageMap) of + Language Properties or object (previousObject) of Relationships is provided in addition to the current one. + This requires that it exists, i.e. in case of modifications and deletions, + but not in the case of creations. showChanges cannot be true in case format is "keyValues". + type: boolean + endpoint: + description: | + Notification endpoint details. + $ref: '#/components/schemas/Endpoint' + status: + description: | + Status of the Notification. It shall be "ok" if the last attempt to notify the subscriber succeeded. + It shall be "failed" if the last attempt to notify the subscriber failed. + type: string + enum: + - ok + - failed + timesSent: + description: | + Number of times that the notification has been sent. Provided by the system when + querying the details of a subscription. + type: number + minimum: 0 + timesFailed: + description: | + Number of times an unsuccessful response (or timeout) has been received when deliverying the notification. + Provided by the system when querying the details of a subscription. + type: number + minimum: 0 + lastNotification: + description: | + Timestamp corresponding to the instant when the last notification has been sent. + Provided by the system when querying the details of a subscription. + type: string + format: date-time + lastFailure: + description: | + Timestamp corresponding to the instant when the last notification resulting in failure + (for instance, in the HTTP binding, an HTTP response code different than 200) has been sent. + Provided by the system when querying the details of a subscription. + type: string + format: date-time + lastSuccess: + description: | + Timestamp corresponding to the instant when the last successful (200 OK response) notification + has been sent. Provided by the system when querying the details of a subscription. + type: string + format: date-time + required: + - endpoint + ###### + # "ProblemDetails" schema from ETSI NFV OAS (BEGIN) + # + ProblemDetails: + description: | + The definition of the general "ProblemDetails" data structure from + IETF RFC 7807 [19] is reproduced inthis structure. Compared to the + general framework defined in IETF RFC 7807 [19], the "status" and + "detail" attributes are mandated to be included by the present document, + to ensure that the response contains additional textual information about + an error. IETF RFC 7807 [19] foresees extensibility of the + "ProblemDetails" type. It is possible that particular APIs in the present + document, or particular implementations, define extensions to define + additional attributes that provide more information about the error. + The description column only provides some explanation of the meaning to + Facilitate understanding of the design. For a full description, see + IETF RFC 7807 [19]. + type: object + required: + - status + - detail + properties: + type: + description: | + A URI reference according to IETF RFC 3986 [5] that identifies the + problem type. It is encouraged that the URI provides human-readable + documentation for the problem (e.g. using HTML) when dereferenced. + When this member is not present, its value is assumed to be + "about:blank". + type: string + format: URI + title: + description: | + A short, human-readable summary of the problem type. It should not + change from occurrence to occurrence of the problem, except for + purposes of localization. If type is given and other than + "about:blank", this attribute shall also be provided. + A short, human-readable summary of the problem + type. It SHOULD NOT change from occurrence to occurrence of the + problem, except for purposes of localization (e.g., using + proactive content negotiation; see [RFC7231], Section 3.4). + type: string + status: + description: | + The HTTP status code for this occurrence of the problem. + The HTTP status code ([RFC7231], Section 6) generated by the origin + server for this occurrence of the problem. + type: integer + detail: + description: | + A human-readable explanation specific to this occurrence of the + problem. + type: string + instance: + description: | + A URI reference that identifies the specific occurrence of the + problem. It may yield further information if dereferenced. + type: string + format: URI + # + # "ProblemDetails" schema from ETSI NFV OAS (END) + ###### + Property: + description: | + 5.2.5 NGSI-LD Property. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - Property + default: Property + value: + description: | + Property value. + oneOf: + - $ref: '#/components/schemas/DateTimeValue' + - $ref: '#/components/schemas/AnyValue' + observedAt: + $ref: '#/components/schemas/ObservedAt' + description: | + Timestamp. See clause 4.8. + type: string + format: date-time + unitCode: + description: | + Property Value's unit code. + type: string + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + previousValue: + description: | + Previous Property value. Only used in notifications. + allOf: + - oneOf: + - $ref: '#/components/schemas/DateTimeValue' + - $ref: '#/components/schemas/AnyValue' + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + Query: + description: | + 5.2.23 This datatype represents the information that is required in order to convey + a query when a "Query Entities" operation is to be performed (as pe clause 5.7.2). + type: object + properties: + type: + description: | + JSON-LD @type. + type: string + enum: + - Query + entities: + description: | + Entity ids, id pattern and Entity types that shall be matched by Entities in order to be retrieved. + type: array + items: + $ref: '#/components/schemas/EntitySelector' + minItems: 1 + attrs: + description: | + List of Attributes that shall be matched by Entities in order to be retrieved. + If not present all Attributes will be retrieved. + type: array + items: + type: string + minItems: 1 + q: + description: | + Query that shall be matched by Entities in order to be retrieved. + type: string + geoQ: + description: | + Geoquery that shall be matched by Entities in order be retrieved. + $ref: '#/components/schemas/GeoQuery' + csf: + description: | + Context source filter that shall be matched by Context Source Registrations describing + Context Sources to be used for retrieving Entities. + type: string + temporalQ: + description: | + Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). + $ref: '#/components/schemas/TemporalQuery' + scopeQ: + description: Scope query. + type: string + lang: + description: Language filter to be applied to the query (clause 4.15). + type: string + required: + - type + Query.temporal: + description: | + 5.2.23 This datatype represents the information that is required in order to convey + a query when a "Query Temporal Evolution of Entities" operation is to be performed (as pe clause 5.7.4). + allOf: + - $ref: '#/components/schemas/Query' + - type: object + properties: + temporalQ: + description: | + Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). + $ref: '#/components/schemas/TemporalQuery' + - required: + - temporalQ + RegistrationInfo: + description: | + 5.2.10 RegistrationInfo. + type: object + properties: + entities: + description: | + Describes the entities for which the CSource may be able to provide information. + type: array + items: + $ref: '#/components/schemas/EntityInfo' + minItems: 1 + propertyNames: + description: | + Describes the Properties that the CSource may be able to provide. + type: array + items: + type: string + minItems: 1 + relationshipNames: + description: | + Describes the Relationships that the CSource may be able to provide. + type: array + items: + type: string + minItems: 1 + RegistrationManagementInfo: + description: | + 5.2.34 This type represents the data to alter the default behaviour of a Context Broker when + making a distributed operation request to a registered Context Source. + type: object + properties: + localOnly: + description: | + If localOnly=true then distributed operations associated to this Context Source Registration + will act only on data held directly by the registered Context Source itself (see clause 4.3.6.4). + type: boolean + cacheDuration: + description: | + Minimal period of time which shall elapse between two consecutive context information + consumption operations (as defined in clause 5.7) related to the same context data will occur. + If the cacheDuration latency period has not been reached, a cached value for the + entity or its attributes shall be returned where available. + type: string + timeout: + description: | + Maximum period of time in milliseconds which may elapse before a + forwarded request is assumed to have failed. + type: number + minimum: 1 + cooldown: + description: | + Minimum period of time in milliseconds which shall elapse before attempting + to make a subsequent forwarded request to the same endpoint after failure. + If requests are received before the cooldown period has expired, a timeout error + response for the registration is automatically returned. + type: number + minimum: 1 + Relationship: + description: | + 5.2.6 NGSI-LD Relationship. + properties: + type: + description: | + Node type. + type: string + enum: + - Relationship + default: Relationship + object: + description: | + Relationship's target object. + type: string + format: uri + observedAt: + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of target relationship objects. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Relationship instance + (see clause 4.5.8). System generated. + type: string + format: uri + readOnly: true + previousObject: + description: | + Previous Relationship's target object. Only used in notifications. + type: string + format: uri + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + Subscription: + oneOf: + - $ref: '#/components/schemas/Subscription.OnChange' + - $ref: '#/components/schemas/Subscription.Periodic' + Subscription.Common: + description: | + 5.2.12 represents a Context Subscription. + type: object + properties: + id: + description: | + Subscription identifier (JSON-LD @id). + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - Subscription + subscriptionName: + description: | + A (short) name given to this Subscription. + type: string + description: + description: | + Subscription description. + type: string + entities: + description: | + Entities subscribed. + type: array + items: + $ref: '#/components/schemas/EntitySelector' + minItems: 1 + notificationTrigger: + description: | + The notification triggers listed indicate what kind of changes shall trigger a notification. + If not present, the default is the combination attributeCreated and attributeUpdated. + entityUpdated is equivalent to the combination attributeCreated, attributeUpdated and attributeDeleted. + type: array + items: + type: string + enum: + - entityCreated + - entityUpdated + - entityDeleted + - attributeCreated + - attributeUpdated + - attributeDeleted + q: + description: | + Query that shall be met by subscribed entities in order to trigger the notification. + type: string + geoQ: + description: | + Geoquery that shall be met by subscribed entities in order to trigger the notification. + $ref: '#/components/schemas/GeoQuery' + csf: + description: | + Context source filter that shall be met by Context Source Registrations describing Context Sources + to be used for Entity Subscriptions. + type: string + isActive: + description: | + Allows clients to temporarily pause the subscription by making it inactive. + true indicates that the Subscription is under operation. + false indicates that the subscription is paused and notifications shall not be delivered. + type: boolean + notification: + description: | + Notification details. + $ref: '#/components/schemas/NotificationParams' + expiresAt: + description: | + Expiration date for the subscription. + type: string + format: date-time + temporalQ: + description: | + Temporal Query to be used only in Context Registration Subscriptions for matching + Context Source Registrations of Context Sources providing temporal information. + $ref: '#/components/schemas/TemporalQuery' + scopeQ: + description: | + Scope query. + type: string + lang: + description: | + Language filter to be applied to the query (clause 4.15). + type: string + # Clause 5.2.2 Common members. System-generated + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true + status: + description: | + Read-only. Provided by the system when querying the details of a subscription. + type: string + enum: + - active + - paused + - expired + readOnly: true + Subscription.Periodic: + allOf: + - $ref: '#/components/schemas/Subscription.Common' + - type: object + properties: + timeInterval: + description: | + Indicates that a notification shall be delivered periodically regardless of attribute changes. + Actually, when the time interval (in seconds) specified in this value field is reached. + type: number + minimum: 1 + - required: + - entities + # - timeInterval + Subscription.OnChange: + allOf: + - $ref: '#/components/schemas/Subscription.Common' + - type: object + properties: + watchedAttributes: + description: | + Watched Attributes (Properties or Relationships). If not defined it means any Attribute. + type: array + items: + type: string + minItems: 1 + throttling: + description: | + Minimal period of time in seconds which shall elapse between two consecutive notifications. + type: number + minimum: 1 + TemporalQuery: + description: | + 5.2.21 This datatype represents a temporal query. + type: object + properties: + timerel: + description: | + Allowed values: "before", "after" and "between". + type: string + enum: + - before + - after + - between + timeAt: + description: | + It shall be a DateTime. + type: string + format: date-time + endTimeAt: + description: | + It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between". + type: string + format: date-time + timeproperty: + description: | + Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". + If not specified, the default is "observedAt". (See clause 4.8). + type: string + enum: + - observedAt + - createdAt + - modifiedAt + - deletedAt + required: + - timerel + - timeAt + TimeInterval: + description: | + 5.2.11 NGSI-LD TimeInterval. + type: object + properties: + startAt: + description: | + Describes the start of the time interval. + type: string + format: date-time + endAt: + description: | + Describes the end of the time interval. If not present the interval is open. + type: string + format: date-time + required: + - startAt + UpdateResult: + description: | + 5.2.18 represents the result of Attribute update (append or update) operations + in the NGSI-LD API regardless of whether local or distributed. + type: object + properties: + updated: + description: | + List of Attributes (represented by their Name) that were appended or updated. + type: array + items: + type: string + notUpdated: + description: | + List which contains the Attributes (represented by their Name) that were not updated, + together with the reason for not being updated. + type: array + items: + $ref: '#/components/schemas/NotUpdatedDetails' + required: + - updated + - notUpdated + + responses: + BadRequest: + description: | + It is used to indicate that the request or its content is incorrect, + see clause 6.3.2. In the returned ProblemDetails structure, the "detail" + attribute should convey more information about the error. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/json+ld: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/geo: + schema: + $ref: '#/components/schemas/ProblemDetails' + Conflict: + description: | + It is used to indicate that the entity or an exclusive or redirect + registration defining the entity already exists, see clause 6.3.2. + In the returned ProblemDetails structure, the "detail" attribute should + convey more information about the error. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/json+ld: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/geo: + schema: + $ref: '#/components/schemas/ProblemDetails' + MultiStatus.BatchOperationResult: + description: | + If the entity input data matches to a registration, the relevant parts of the request are forwarded + as a distributed operation. In the case when an error response is received back from any distributed + operation, a response body containing the result returned from each registration is returned in a + BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, + fails or times out, see clause 6.3.17. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/BatchOperationResult' + application/json+ld: + schema: + $ref: '#/components/schemas/BatchOperationResult' + MultiStatus.UpdateResult: + description: | + Only the Attributes included in the response payload body were successfully appended. + + If the entity input data matches to a registration, the relevant parts of the request are + forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, a response + body containing the result returned from each registration is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateResult' + application/json+ld: + schema: + $ref: '#/components/schemas/UpdateResult' + NotFound: + description: | + It is used when a client provided an entity identifier (URI) not known + to the system, see clause 6.3.2. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/json+ld: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/geo: + schema: + $ref: '#/components/schemas/ProblemDetails' + ServiceUnavailable: + description: | + It is used when re-downloading fails. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/json+ld: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/geo: + schema: + $ref: '#/components/schemas/ProblemDetails' + Unprocessable: + description: | + It is used to indicate that the operation is not available, + see clause 6.3.2. In the returned ProblemDetails structure, + the "detail" attribute should convey more information about the error. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/json+ld: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/geo: + schema: + $ref: '#/components/schemas/ProblemDetails' \ No newline at end of file -- GitLab From daf3b262f6b945890bebd36cb79a6cdbc054a569 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 14 Mar 2024 01:29:58 +0100 Subject: [PATCH 003/112] Update links within the README file and add a link to view the original NGSI-LD OAS in the Swagger Editor of ETSI Forge. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f1e138c..e14ae76 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API spe ### Navigate API -* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) +* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) +* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) * [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) ## Developers -- GitLab From 4db3f1e288e56198a14afb2db637218879cc00af Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 14 Mar 2024 01:32:51 +0100 Subject: [PATCH 004/112] Fixing an indentation issue with the additionalProperties field in the Schemas of Entity and Relationship within the NGSI-LD OAS. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 704a431..2db9936 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -5013,7 +5013,7 @@ components: minimum: 1 - required: - entities - # - timeInterval + - timeInterval Subscription.OnChange: allOf: - $ref: '#/components/schemas/Subscription.Common' -- GitLab From d6b7f9e25c81800f3730880056229cf09c8e13cc Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 14 Mar 2024 01:40:34 +0100 Subject: [PATCH 005/112] Eliminate the required option within the Subcription.Periodic schema for fields entities and timeInterval. Move the required option for the entities fields to the schemas statement of the Subscription request body. --- ngsi-ld-api.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2db9936..9fe0f97 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3267,6 +3267,7 @@ components: - $ref: '#/components/schemas/Subscription' - required: - type + - entities application/json+ld: schema: allOf: @@ -5011,9 +5012,6 @@ components: Actually, when the time interval (in seconds) specified in this value field is reached. type: number minimum: 1 - - required: - - entities - - timeInterval Subscription.OnChange: allOf: - $ref: '#/components/schemas/Subscription.Common' -- GitLab From 3ba1f8b4764126a863bf2de04a02914fbf377543 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 14 Mar 2024 01:46:14 +0100 Subject: [PATCH 006/112] Adding a folder for defining examples of custom OpenAPI schemas that are compliant with the NGSI-LD OAS. --- .../customSchemas/sensor-custom-schemas.yaml | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 examples/customSchemas/sensor-custom-schemas.yaml diff --git a/examples/customSchemas/sensor-custom-schemas.yaml b/examples/customSchemas/sensor-custom-schemas.yaml new file mode 100644 index 0000000..f748552 --- /dev/null +++ b/examples/customSchemas/sensor-custom-schemas.yaml @@ -0,0 +1,39 @@ +openapi: 3.0.3 +info: + title: Example schemas for a temperature sensor + version: 0.0.1 + description: | + Example schemas compliant with the NGSI-LD OAS V1.6.1 metamodel according to ETSI GS CIM 009 V1.6.1. +paths: {} +components: + schemas: + TemperatureSensor: + description: | + NGSI-LD Entity Type that represents a temperature sensor. + allOf: + - $ref: 'https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml#/components/schemas/Entity' + - type: object + properties: + type: + description: NGSI-LD Entity identifier. It has to be TemperatureSensor. + type: string + enum: + - TemperatureSensor + default: TemperatureSensor + temperature: + $ref: '#/components/schemas/Temperature' + - required: + - type + - temperature + Temperature: + description: | + NGSI-LD Property Type. The temperature measurement. + allOf: + - $ref: 'https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml#/components/schemas/Property' + - type: object + properties: + value: + type: number + required: + - value + additionalProperties: false \ No newline at end of file -- GitLab From 26856b4feeda61bf08c3cf4339572282ae82a345 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 14 Mar 2024 10:50:35 +0100 Subject: [PATCH 007/112] Relaxing the tenant name requirement. Eliminate the URI format for the tenant property of the CsourceRegistration schema within the NGSI-LD OAS. A tenant name can now be a string. It can still be a URI (string), but this is no longer required (Table 5.2.9-1 CsourceRegistration data type definition - ETSI GS CIM 009 V1.7.1). --- README.md | 2 +- ngsi-ld-api.yaml | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index e14ae76..19b5df0 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API spe ### Specification Document -* [ETSI GS CIM 009](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.06.01_60/gs_CIM009v010601p.pdf) +* [ETSI GS CIM 009](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.07.01_60/gs_CIM009v010701p.pdf) ### Navigate API diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9fe0f97..22bb6b0 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3613,7 +3613,6 @@ components: are related to the information registered in this Context Source Registration. If not present, the default tenant is assumed. Should only be present in systems supporting multi-tenancy. type: string - format: uri observationInterval: description: | If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity -- GitLab From a4b3596eba49de79288ab3c591a8528a3c1c79d3 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 21 Mar 2024 10:46:00 +0100 Subject: [PATCH 008/112] Fixing some issues within the NGSI-OAS v1.6.1 regarding Context Information Consumption operations: 1) Fixing tags section for 5.8.3-Retrieve Subscription y 5.8.4-Query Subscriptions to Context Information Subscription; 2) Including description of 5.7.6-Retrieve Details of Available Entity Types operation together with the 5.7.5-Retrieve Available Entity Types operation; 3) Including description of 5.7.9-Retrieve Details of Available Attributes operation together with the 5.7.8-Retrieve Available Attributes operation; 4) Fixing the EntityTypeList type definition within schema content of the response for 5.7.5-Retrieve Available Entity Types operation and 5.7.6-Retrieve Details of Available Entity Types operations. Pending actions: solving doubts with the definition of the parameters Query.geometryProperty, Query.geoproperty, and Query.options.entities, and Query.datasetId. --- ngsi-ld-api.yaml | 50 ++++++++++++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9fe0f97..5ef3e4e 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -189,7 +189,9 @@ paths: - $ref: '#/components/parameters/Path.entityId' # Query params - $ref: '#/components/parameters/Query.attrs' + # REVIEW GeoProperty - $ref: '#/components/parameters/Query.geometryProperty' + # REVIEW Options entities - $ref: '#/components/parameters/Query.lang' - $ref: '#/components/parameters/Query.options.entities' # Local Query param @@ -923,7 +925,7 @@ paths: $ref: '#/components/responses/Conflict' get: tags: - - Context Information Consumption + - Context Information Subscription summary: | Retrieve list of Subscriptions description: | @@ -979,7 +981,7 @@ paths: /subscriptions/{subscriptionId}: get: tags: - - Context Information Consumption + - Context Information Subscription summary: | Subscription retrieval by id description: | @@ -1653,7 +1655,7 @@ paths: summary: | Query entities based on POST description: | - 5.7.2 Query Entity. + 5.7.2 Query Entities (batch entity queries only). operationId: queryBatch parameters: # Local Query param @@ -1777,7 +1779,7 @@ paths: summary: | Temporal Representation of Entity creation description: | - 5.6.11 Upsert Temporal Representation. + 5.6.11 Create or Update Temporal Representation of an Entity. This operation allows creating or updating (by adding new Attribute instances) a Temporal Representation of an Entity. @@ -1992,7 +1994,7 @@ paths: summary: | Temporal Representation of Entity Attribute instance addition description: | - 5.6.12 Append Entity Attributes. + 5.6.12 Add Attributes to Temporal Representation of an Entity. This operation allows modifying a Temporal Representation of an Entity by adding new Attribute instances. operationId: appendAttrsTemporal @@ -2187,13 +2189,18 @@ paths: tags: - Context Information Consumption summary: | - Retrieve available entity types + Retrieve Available Entity Types & Retrieve Details of Available Entity Types description: | 5.7.5 Retrieve Available Entity Types. This operation allows retrieving a list of NGSI-LD entity types for which entity instances exist within the NGSI-LD system. - operationId: retrieveTypes + + 5.7.6 Retrieve Details of Available Entity Types. + + This operation allows retrieving a list with a detailed representation of + NGSI-LD entity types for which entity instances exist within the NGSI-LD system. + operationId: retrieveEntityTypes parameters: # Query params - name: details @@ -2226,9 +2233,7 @@ paths: application/json: schema: oneOf: - - type: array - items: - $ref: '#/components/schemas/EntityTypeList' + - $ref: '#/components/schemas/EntityTypeList' - type: array items: $ref: '#/components/schemas/EntityType' @@ -2242,9 +2247,7 @@ paths: properties: '@context': $ref: '#/components/schemas/LdContext' - - type: array - items: - $ref: '#/components/schemas/EntityTypeList' + - $ref: '#/components/schemas/EntityTypeList' - allOf: - type: object required: @@ -2312,12 +2315,17 @@ paths: tags: - Context Information Consumption summary: | - Retrieve Available Attributes + Retrieve Available Attributes & Retrieve Details of Available Attributes description: | - 5.7.8 Retrieve Available attributes. + 5.7.8 Retrieve Available Attributes. This operation allows retrieving a list of NGSI-LD attributes that belong to entity instances existing within the NGSI- LD system. + + 5.7.9 Retrieve Details of Available Attributes. + + This operation allows retrieving a list with a detailed representation of NGSI-LD + attributes that belong to entity instances existing within the NGSI-LD system. operationId: retrieveAttributes parameters: # Query params @@ -2385,13 +2393,13 @@ paths: summary: | Retrieve Available Attribute Information description: | - 5.7.10 Retrieve Available Attribute information. + 5.7.10 Retrieve Available Attribute Information. This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes - the attribute name (as short name if available in the provided @context) and the type names - for which entity instances exist that have the respective attribute, a count of available - attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty). + the attribute name (as short name if available in the provided @context) and the type names + for which entity instances exist that have the respective attribute, a count of available + attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty). operationId: retrieveAttrInfo parameters: # Path params @@ -2840,6 +2848,7 @@ components: schema: type: string required: false + # REVIEW Query.datasetId: name: datasetId in: query @@ -2906,6 +2915,7 @@ components: type: string format: pattern required: false + # REVIEW (5.7.1 y 6.4.3/6.5.3) Query.geometryProperty: name: geometryProperty in: query @@ -2934,6 +2944,7 @@ components: - Polygon - MultiPolygon required: false + # REVIEW (5.7.1 y 6.4.3/6.5.3) Query.geoproperty: name: geoproperty in: query @@ -3036,6 +3047,7 @@ components: type: string format: date-time required: false + # REVIEW Query.options.entities: name: options in: query -- GitLab From 5debf334456ddf9a22e4475f55743198299d132d Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 11:27:15 +0100 Subject: [PATCH 009/112] Fix ld+json request body example in Batch Create The previous body contained an array of entities and the @context, instead of having an array of Entities with dedicated @context fields --- ngsi-ld-api.yaml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9fe0f97..1fc30a6 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1350,15 +1350,16 @@ paths: allOf: - type: array items: - $ref: '#/components/schemas/Entity' - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - required: - - id - - type - - '@context' + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '201': description: | -- GitLab From 5d4b1c70e62a59fe5d2683f3bdb6f518f2c1b6bd Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:33:13 +0100 Subject: [PATCH 010/112] Removed Accept headers in POST entityOperations/create and errored responses In CIM 6.3.6 HTTP response common requirements it is stated that the provided "Accept header" is ignored when there is an error. Not much is said about multi-status (207), but we can safely say that the responses should be application/json as the @context is present in the request. Definitely no geo resourse is returned in multi-status responses --- ngsi-ld-api.yaml | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 1fc30a6..fffea6c 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1375,18 +1375,6 @@ paths: type: array items: type: string - application/json+ld: - schema: - allOf: - - type: object - required: - - '@context' - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - type: array - items: - type: string '207': description: | If only some or none of the entities have been successfully created, a response body containing the @@ -5119,12 +5107,6 @@ components: application/json: schema: $ref: '#/components/schemas/ProblemDetails' - application/json+ld: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/geo: - schema: - $ref: '#/components/schemas/ProblemDetails' Conflict: description: | It is used to indicate that the entity or an exclusive or redirect @@ -5158,9 +5140,6 @@ components: application/json: schema: $ref: '#/components/schemas/BatchOperationResult' - application/json+ld: - schema: - $ref: '#/components/schemas/BatchOperationResult' MultiStatus.UpdateResult: description: | Only the Attributes included in the response payload body were successfully appended. -- GitLab From 503518d7b2893b0b74d81601358419373c0bafd2 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:41:00 +0100 Subject: [PATCH 011/112] Fix capitalization in batch entity creation summary --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index fffea6c..5e8b18e 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1320,7 +1320,7 @@ paths: tags: - Context Information Provision summary: | - Batch Entity creation + Batch Entity Creation description: | 5.6.7 Batch Entity Creation. -- GitLab From a31d398c592c826d376ca03cc31c2bc3ded0daea Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:41:23 +0100 Subject: [PATCH 012/112] Update batch entity upsert summary --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5e8b18e..fe51afd 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1400,7 +1400,7 @@ paths: tags: - Context Information Provision summary: | - Batch Entity create or update (upsert) + Batch Entity Creation or Update (Upsert) description: | 5.6.8 Batch Entity Upsert. -- GitLab From b3ce081e39f1c3707c571f45de69e2f069b1fcbd Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:45:28 +0100 Subject: [PATCH 013/112] Fix example of the request body of the Batch Upsert Operation --- ngsi-ld-api.yaml | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index fe51afd..9943bfe 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1433,15 +1433,16 @@ paths: allOf: - type: array items: - $ref: '#/components/schemas/Entity' - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - required: - - id - - type - - '@context' + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '201': description: | @@ -1459,11 +1460,6 @@ paths: type: array items: type: string - application/json+ld: - schema: - type: array - items: - type: string '204': description: | If all entities already existed and are successfully updated, there is no payload body in the response. -- GitLab From 94dbbcd82aef9d434baf4fb49cfed62a1c3aada6 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:46:23 +0100 Subject: [PATCH 014/112] Fix capitalization in batch entity update summary --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9943bfe..102df59 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1491,7 +1491,7 @@ paths: tags: - Context Information Provision summary: | - Batch Entity update + Batch Entity Update description: | 5.6.9 Batch Entity Update. -- GitLab From c3e5390fd9403151aebe404e92468a343585c001 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:52:51 +0100 Subject: [PATCH 015/112] Refactor example of response body in Batch Entity Update and capitalize a letter in the summary of Batch Entity Delete --- ngsi-ld-api.yaml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 102df59..2effbd4 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1523,15 +1523,16 @@ paths: allOf: - type: array items: - $ref: '#/components/schemas/Entity' - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - required: - - id - - type - - '@context' + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '204': description: | @@ -1564,7 +1565,7 @@ paths: tags: - Context Information Provision summary: | - Batch Entity delete + Batch Entity Delete description: | 5.6.10 Batch Entity Delete. -- GitLab From 53b568e6b87b41e06e79a9d507bd8bf9db7b71b6 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 12:57:42 +0100 Subject: [PATCH 016/112] Remove Content-Type ld+json from Batch Entity Delete The content is an array of strings and it is not supposed to contain the @context field anywhere --- ngsi-ld-api.yaml | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2effbd4..68add76 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1585,25 +1585,7 @@ paths: schema: type: array items: - allOf: - - $ref: '#/components/schemas/Entity' - - required: - - id - - type - application/json+ld: - schema: - allOf: - - type: array - items: - $ref: '#/components/schemas/Entity' - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - required: - - id - - type - - '@context' + type: string responses: '204': description: | -- GitLab From 91b9e65b64ca3a1e001ae97b0b7f4fb5e02c062e Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 13:21:31 +0100 Subject: [PATCH 017/112] Fix local description field being overridden by the one in the schema --- ngsi-ld-api.yaml | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 68add76..7a7577a 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1376,6 +1376,8 @@ paths: items: type: string '207': + allOf: + - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. @@ -1392,7 +1394,6 @@ paths: is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. - $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/upsert: @@ -1467,12 +1468,14 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': + allOf: + - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | - If only some or none of the entities have been successfully created, a response body containing the + If only some or none of the entities have been successfully created or updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. - It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + It contains two arrays. The first array ('success') contains the URIs of the successfully created or updated entities, while the second array ('errors') contains information about the error for each - of the entities that could not be created. There is no restriction + of the entities that could not be created or updated. There is no restriction as to the order of the Entity Ids in the arrays. If any of the entities matches to a registration, the relevant parts of the request @@ -1483,7 +1486,6 @@ paths: is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. - $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/update: @@ -1536,11 +1538,13 @@ paths: responses: '204': description: | - If all entities already existed and are successfully updated, there is no payload body in the response. + If all entities have been successfully updated, there is no payload body in the response. headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': + allOf: + - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. @@ -1557,7 +1561,6 @@ paths: is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. - $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/delete: @@ -1594,6 +1597,8 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': + allOf: + - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If some or all of the entities have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned @@ -1611,7 +1616,6 @@ paths: fails or times out, see clause 6.3.17. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. - $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/query: -- GitLab From bfe830ae74d5915df32c3158b3c14be49d807f3d Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 13:25:23 +0100 Subject: [PATCH 018/112] Update batch operation response structure in NGSI-LD API --- ngsi-ld-api.yaml | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 7a7577a..1fdf11a 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1546,21 +1546,34 @@ paths: allOf: - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | - If only some or none of the entities have been successfully created, a response body containing the - result of each operation contained in the batch is returned in a BatchOperationResult structure. - It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, - while the second array ('errors') contains information about the error for each - of the entities that could not be created. There is no restriction - as to the order of the Entity Ids in the arrays. + If only some or none of the entities have + been successfully updated, a response + body containing the result of each operation + contained in the batch is returned in a + BatchOperationResult structure. It contains + two arrays. The first array ('success') + contains the URIs of the successfully + updated entities, while the second array + ('errors') contains information about the + error for each of the entities that could not + be updated. There is no restriction as to the + order of the Entity Ids in the arrays. - If any of the entities matches to a registration, the relevant parts of the request - are forwarded as a distributed operation. + If any of the entities matches to a + registration, the relevant parts of the + request are forwarded as a distributed + operation. - In the case when an error response is received back from any distributed operation, - a response body containing the result returned from each registration - is returned in a BatchOperationResult structure. + In the case when an error response is + received back from any distributed + operation, a response body containing the + result returned from each registration is + returned in a BatchOperationResult + structure. - Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + Errors can occur whenever a distributed + operation is unsupported, fails or times out, + see clause 6.3.17. '400': $ref: '#/components/responses/BadRequest' /entityOperations/delete: -- GitLab From 0f6ee95f7568dd22c5981e123c98709543c7a6ad Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 13:32:36 +0100 Subject: [PATCH 019/112] Remove unneeded "allOf" statements in the schema definitions of the request body of batch entity operations --- ngsi-ld-api.yaml | 104 +++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 53 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 1fdf11a..b29456d 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1347,19 +1347,18 @@ paths: - type application/json+ld: schema: - allOf: - - type: array - items: - allOf: - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - $ref: '#/components/schemas/Entity' - - required: - - id - - type - - '@context' + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '201': description: | @@ -1431,19 +1430,18 @@ paths: - type application/json+ld: schema: - allOf: - - type: array - items: - allOf: - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - $ref: '#/components/schemas/Entity' - - required: - - id - - type - - '@context' + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '201': description: | @@ -1522,19 +1520,18 @@ paths: - type application/json+ld: schema: - allOf: - - type: array - items: - allOf: - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - $ref: '#/components/schemas/Entity' - - required: - - id - - type - - '@context' + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '204': description: | @@ -1687,7 +1684,7 @@ paths: tags: - Context Information Provision summary: | - Batch Entity merge + Batch Entity Merge description: | 5.6.20 Batch Entity Merge. @@ -1716,18 +1713,18 @@ paths: - type application/json+ld: schema: - allOf: - - type: array - items: - $ref: '#/components/schemas/Entity' - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - required: - - id - - type - - '@context' + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' responses: '204': description: | @@ -1736,6 +1733,8 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': + allOf: + - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully merged, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. @@ -1752,7 +1751,6 @@ paths: is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. - $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /temporal/entities: -- GitLab From 30806e5ec4c62a80c66febb0eadaec02ebaf2259 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 22 Mar 2024 13:39:53 +0100 Subject: [PATCH 020/112] Show the @context field on top of the Query example and on top of the Batch Post Query response body example (LD+JSON) --- ngsi-ld-api.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index b29456d..9e1400b 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1636,6 +1636,8 @@ paths: Query entities based on POST description: | 5.7.2 Query Entity. + + This operation allows querying an NGSI-LD system. operationId: queryBatch parameters: # Local Query param @@ -1668,11 +1670,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - id - type @@ -3220,11 +3222,11 @@ components: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Query' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Query' - required: - '@context' QueryTemporal: -- GitLab From 3aac2dec0df541697097c5ac0d1c343baeae6dbd Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 25 Mar 2024 12:25:56 +0100 Subject: [PATCH 021/112] Fix typo in query description --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9e1400b..c807e83 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -4693,7 +4693,7 @@ components: Query: description: | 5.2.23 This datatype represents the information that is required in order to convey - a query when a "Query Entities" operation is to be performed (as pe clause 5.7.2). + a query when a "Query Entities" operation is to be performed (as per clause 5.7.2). type: object properties: type: -- GitLab From 41704b3aca07be940c01b17930e47139429ba6a8 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 25 Mar 2024 12:50:31 +0100 Subject: [PATCH 022/112] Removed definition of requestBodies/Query because it prevents to display the "description" --- ngsi-ld-api.yaml | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index c807e83..8d0d136 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1647,7 +1647,20 @@ paths: - $ref: '#/components/parameters/Headers.ngsildTenant' requestBody: description: Payload body in the request contains a JSON-LD object which represents the query to be performed. - $ref: '#/components/requestBodies/Query' + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Query' + - required: + - '@context' responses: '200': description: | @@ -3214,21 +3227,6 @@ components: $ref: '#/components/schemas/LdContext' - required: - '@context' - Query: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/json+ld: - schema: - allOf: - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - $ref: '#/components/schemas/Query' - - required: - - '@context' QueryTemporal: content: application/json: -- GitLab From 4e6090dcdafc7990919f1492475455327b77b693 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Tue, 2 Apr 2024 12:43:22 +0200 Subject: [PATCH 023/112] Update response structure in distributed operations --- ngsi-ld-api.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 8d0d136..531e025 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -5142,7 +5142,9 @@ components: forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response - body containing the result returned from each registration is returned in a BatchOperationResult structure. + body containing the result returned from each registration is returned in a UpdateResult structure. + + Names of the Attributes included in the UpdateResult structure are represented as Fully Qualified Names as per clause 6.3.6. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. headers: @@ -5152,9 +5154,6 @@ components: application/json: schema: $ref: '#/components/schemas/UpdateResult' - application/json+ld: - schema: - $ref: '#/components/schemas/UpdateResult' NotFound: description: | It is used when a client provided an entity identifier (URI) not known -- GitLab From 66b5d5c2e07c748b43c42b9eef957c9d681eab61 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 11:07:09 +0200 Subject: [PATCH 024/112] Update description for MultiStatus.UpdateResult Response (Components section). --- ngsi-ld-api.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9fe0f97..ac27d63 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2667,7 +2667,7 @@ components: In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", - then the associated @context shall be provided only by using the JSON- LD Link header. + then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise. @@ -5162,7 +5162,8 @@ components: $ref: '#/components/schemas/BatchOperationResult' MultiStatus.UpdateResult: description: | - Only the Attributes included in the response payload body were successfully appended. + Only the Attributes included in the response payload body were successfully appended. If no Attributes + were successfully updated the updated array of UpdateResult (see clause 5.2.18) will be empty. If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. -- GitLab From 6d058b3b6f5f803e59cff2902dd35ab036c9fe08 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 11:33:35 +0200 Subject: [PATCH 025/112] Capitalize and fix summary and description for operation 5.6.2 Update Entity Attributes. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index ac27d63..3b2c50b 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -455,9 +455,9 @@ paths: tags: - Context Information Provision summary: | - Update attributes of an Entity + Update Attributes of an Entity description: | - 5.6.2 Update Entity attributes. + 5.6.2 Update Entity Attributes. This operation allows modifying an existing NGSI-LD Entity by updating already existing Attributes (Properties or Relationships). -- GitLab From 3105c32bc02f7d6163036e6bfc9bba02ff9b8d55 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 11:59:27 +0200 Subject: [PATCH 026/112] Capitalize and fix summary and description for operation 5.6.3 Append Entity Attributes. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 3b2c50b..abd2ab2 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -403,9 +403,9 @@ paths: tags: - Context Information Provision summary: | - Append attributes to Entity + Append Attributes to Entity description: | - 5.6.3 Append Entity attributes. + 5.6.3 Append Entity Attributes. This operation allows modifying an NGSI-LD Entity by adding new attributes (Properties or Relationships). -- GitLab From 168afb649925e6462f62a6372db45fc0c6444c9b Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 12:10:24 +0200 Subject: [PATCH 027/112] Capitalize and fix summary and description for operation 5.6.4 Partial Attribute Update. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index abd2ab2..36d7bab 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -505,9 +505,9 @@ paths: tags: - Context Information Provision summary: | - Partial Attribute update + Partial Attribute Update description: | - 5.6.4 Partial Attribute update. + 5.6.4 Partial Attribute Update. This operation allows performing a partial update on an NGSI-LD Entity's Attribute (Property or Relationship). A partial update only changes the elements provided in an Entity Fragment, leaving the rest as they are. -- GitLab From 40d5ea36dff121f8365dfdc2e428490a173f2501 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 12:18:40 +0200 Subject: [PATCH 028/112] Update description for operation 5.6.5 Delete Entity Attribute. --- ngsi-ld-api.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 36d7bab..1b221b7 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -545,6 +545,9 @@ paths: Attribute delete description: | 5.6.5 Delete Entity Attribute. + + This operation allows deleting an NGSI-LD Entity's Attribute (Property or Relationship). + The Attribute itself and all its children shall be deleted. operationId: deleteAttrs parameters: # Path params -- GitLab From 4974a2eedd422be7da43527d10999aed25a1efbe Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 13:19:10 +0200 Subject: [PATCH 029/112] Capitalize name of operation 5.6.17 Merge Entity within its description. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 1b221b7..5482dbb 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -292,7 +292,7 @@ paths: summary: | Entity merge by id description: | - 5.6.17 Merge entity. + 5.6.17 Merge Entity. This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch processing rules defined in IETF RFC 7396 by adding new Attributes (Properties or Relationships) -- GitLab From def818482fd6e120c6938232a365280c36427aa4 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 13:21:15 +0200 Subject: [PATCH 030/112] Capitalize name of operation 5.6.18 Replace Entity within its description. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5482dbb..87edf38 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -354,7 +354,7 @@ paths: summary: | Entity replacement by id description: | - 5.6.18 Replace entity. + 5.6.18 Replace Entity. This operation allows the modification of an existing NGSI-LD Entity by replacing all of the Attributes (Properties or Relationships). -- GitLab From ef9a87553ecedec187537655866fbda294c0b636 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 13:26:55 +0200 Subject: [PATCH 031/112] Capitalize name of operation 5.6.19 Attribute Replace within its description. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 87edf38..214e7dc 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -580,7 +580,7 @@ paths: summary: | Attribute replace description: | - 5.6.19 Attribute replace. + 5.6.19 Attribute Replace. This operation allows the replacement of a single Attribute (Property or Relationship) within an NGSI-LD Entity. -- GitLab From dda952a8bca281e9b1220815bc7f9f8952607cb6 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 14:11:25 +0200 Subject: [PATCH 032/112] Update share summary for 5.7.5 Retrieve Available Entity Types and 5.7.6 Retrieve Details of Available Entity Types operations. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5ef3e4e..8056812 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2189,7 +2189,7 @@ paths: tags: - Context Information Consumption summary: | - Retrieve Available Entity Types & Retrieve Details of Available Entity Types + Retrieve available entity types description: | 5.7.5 Retrieve Available Entity Types. -- GitLab From 1ef26dea66a04afecae558c05209ecf794049ac5 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 14:13:54 +0200 Subject: [PATCH 033/112] Update operationId for 5.7.7 Retrieve Available Entity Type information operation. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 8056812..23f1832 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2275,7 +2275,7 @@ paths: instances and details about attributes that existing instances of this entity type have, including their name (as short name if available in the provided @context) and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty). - operationId: retrieveTypeInfo + operationId: retrieveEntityTypeInfo parameters: # Path params - $ref: '#/components/parameters/Path.type' -- GitLab From a83e8ceb03e982746a5aeca272344da7738c52b7 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 14:19:50 +0200 Subject: [PATCH 034/112] Update shared summary and operationId for 5.7.8 Retrieve Available Attributes and 5.7.9 Retrieve Details of Available Attributes operations. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 23f1832..d9639ae 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2315,7 +2315,7 @@ paths: tags: - Context Information Consumption summary: | - Retrieve Available Attributes & Retrieve Details of Available Attributes + Available attributes description: | 5.7.8 Retrieve Available Attributes. @@ -2326,7 +2326,7 @@ paths: This operation allows retrieving a list with a detailed representation of NGSI-LD attributes that belong to entity instances existing within the NGSI-LD system. - operationId: retrieveAttributes + operationId: retrieveAttrTypes parameters: # Query params - name: details -- GitLab From 97470e3789520703f742b85888a5f3ae0959a818 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 3 Apr 2024 14:22:24 +0200 Subject: [PATCH 035/112] Update summary and operationId for 5.7.10 Retrieve Available Attribute Information operation. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index d9639ae..db48d8d 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2391,7 +2391,7 @@ paths: tags: - Context Information Consumption summary: | - Retrieve Available Attribute Information + Details about available attribute description: | 5.7.10 Retrieve Available Attribute Information. @@ -2400,7 +2400,7 @@ paths: the attribute name (as short name if available in the provided @context) and the type names for which entity instances exist that have the respective attribute, a count of available attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty). - operationId: retrieveAttrInfo + operationId: retrieveAttrTypeInfo parameters: # Path params - $ref: '#/components/parameters/Path.attrId' -- GitLab From e9bd67250b1fc554c7b0dec6da6a68df51b40939 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 4 Apr 2024 00:42:27 +0200 Subject: [PATCH 036/112] Including options.sysAttrs paramenter within the 5.8.3 Retrieve Subscription operation. As stated in 6.3.11 Including system generated attributes: For HTTP GET operations performed over the resources /entities/, /subscriptions/, /csourceRegistrations/, /csourceSubscriptions/ and all of its sub-resources, implementations shall support the parameter options.sysAttrs. --- ngsi-ld-api.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9fe0f97..6733e2d 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -990,6 +990,8 @@ paths: parameters: # Path params - $ref: '#/components/parameters/Path.subscriptionId' + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' # Local Query param - $ref: '#/components/parameters/Query.local' # Request headers -- GitLab From e797b930cdd10bb68120cc4b01de57335812af1a Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 4 Apr 2024 00:50:11 +0200 Subject: [PATCH 037/112] Eliminating the NGSILD-Warning header from the BadRequest and NotFound responses within the 5.8.3 Retrieve Subscription operation. --- ngsi-ld-api.yaml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 6733e2d..fc0a238 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1027,14 +1027,8 @@ paths: - notification - '@context' '400': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '404': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' patch: tags: -- GitLab From 597bd261ce10ab02d53ba7f3231647b37163d25e Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 4 Apr 2024 14:13:28 +0200 Subject: [PATCH 038/112] Fixing tags for 5.8.3 Retrieve Subscription and 5.8.4 Query Subscriptions operation. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index fc0a238..e71a43a 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -923,7 +923,7 @@ paths: $ref: '#/components/responses/Conflict' get: tags: - - Context Information Consumption + - Context Information Subscription summary: | Retrieve list of Subscriptions description: | @@ -979,7 +979,7 @@ paths: /subscriptions/{subscriptionId}: get: tags: - - Context Information Consumption + - Context Information Subscription summary: | Subscription retrieval by id description: | -- GitLab From 26146b3a04c832ba4c3c08e0cff2ed277ca601b2 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Fri, 5 Apr 2024 15:34:51 +0200 Subject: [PATCH 039/112] Fix typo in required field name in BatchOperationResult schema --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 531e025..aecd076 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3491,7 +3491,7 @@ components: $ref: '#/components/schemas/BatchEntityError' required: - success - - error + - errors CsourceNotification: description: | 5.3.2 This datatype represents the parameters that allow building a Context Source Notification -- GitLab From 6232626d79333ffebdb5f260af171f626e6d9171 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 8 Apr 2024 09:47:23 +0200 Subject: [PATCH 040/112] Add support for application/geo+json in API response of POST query --- ngsi-ld-api.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index aecd076..b2c5be2 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1692,6 +1692,9 @@ paths: - id - type - '@context' + application/geo+json: + schema: + $ref: '#/components/schemas/FeatureCollection' '400': $ref: '#/components/responses/BadRequest' /entityOperations/merge: -- GitLab From 244ae197beebd8d16986b3fdcce4f6b6f477480f Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Tue, 9 Apr 2024 13:55:00 +0200 Subject: [PATCH 041/112] Add options parameter to queryBatch API --- ngsi-ld-api.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index b2c5be2..b204a00 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1641,7 +1641,19 @@ paths: operationId: queryBatch parameters: # Local Query param + - $ref: '#/components/parameters/Query.count' + - $ref: '#/components/parameters/Query.limit' - $ref: '#/components/parameters/Query.local' + - name: options + in: query + style: form + explode: false + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/options.representation' + - $ref: '#/components/schemas/options.sysAttrs' # Request headers - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' -- GitLab From db293d24478541881e0cc2ebcda96f482da89de4 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 10 Apr 2024 21:32:27 +0200 Subject: [PATCH 042/112] Adding entities required field within the application/json+ld content for Subscription Request Body. Recovering the NGSILD-Warning header from the BadRequest and NotFound responses within the 5.8.3 Retrieve Subscription operation. --- ngsi-ld-api.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index e71a43a..22d649a 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1027,8 +1027,14 @@ paths: - notification - '@context' '400': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '404': + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' patch: tags: @@ -3274,6 +3280,7 @@ components: $ref: '#/components/schemas/LdContext' - required: - type + - entities - '@context' SubscriptionFragment: content: -- GitLab From f788ed29f32c0a50cdf69cf6920a31839111ade9 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 10 Apr 2024 21:36:24 +0200 Subject: [PATCH 043/112] Removing SubscriptionFragment Request Body and reusing Subscription Request Body. --- ngsi-ld-api.yaml | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 22d649a..9276d5a 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1057,7 +1057,7 @@ paths: requestBody: description: | Subscription Fragment including id, type and any other subscription field to be changed. - $ref: '#/components/requestBodies/SubscriptionFragment' + $ref: '#/components/requestBodies/Subscription' responses: '204': description: | @@ -1276,7 +1276,7 @@ paths: description: | Subscription Fragment including id, type and any other context source registration subscription field to be changed. - $ref: '#/components/requestBodies/SubscriptionFragment' + $ref: '#/components/requestBodies/Subscription' responses: '204': description: | @@ -3282,21 +3282,6 @@ components: - type - entities - '@context' - SubscriptionFragment: - content: - application/json: - schema: - $ref: '#/components/schemas/Subscription' - application/json+ld: - schema: - allOf: - - $ref: '#/components/schemas/Subscription' - - type: object - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - required: - - '@context' schemas: AnyValue: description: Any JSON value as defined by IETF RFC 8259. -- GitLab From 5069fa917254d43b4f076b6ceb67897b0a5e9c8c Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 10 Apr 2024 22:07:05 +0200 Subject: [PATCH 044/112] Adding NGSILD-Tenant header within HTTP 200 response for 5.8.4 Query Subscriptions operation. --- ngsi-ld-api.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 214e7dc..5a768ad 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -949,6 +949,8 @@ paths: description: | A response body containing a list of subscriptions. headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' NGSILD-Results-Count: $ref: '#/components/headers/NGSILD-Results-Count' content: @@ -1003,6 +1005,8 @@ paths: description: | A response body containing the JSON-LD representation of the target subscription. headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' NGSILD-Warning: $ref: '#/components/headers/NGSILD-Warning' content: -- GitLab From 3a587f0818c60086ad6a0605c7091c62649eb842 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 10 Apr 2024 23:03:13 +0200 Subject: [PATCH 045/112] Show the @context field on top of the request and response bodies for the Subscription operations. --- ngsi-ld-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9276d5a..bc718d9 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -964,11 +964,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/Subscription' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' - required: - id - type @@ -1016,11 +1016,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Subscription' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' - required: - id - type @@ -3273,11 +3273,11 @@ components: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Subscription' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' - required: - type - entities -- GitLab From d0a0a61510598becca89335c8aca34e0dc861257 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 10 Apr 2024 23:28:09 +0200 Subject: [PATCH 046/112] Show the @context field on top of the request and response bodies for the Context Information Provision operations. --- ngsi-ld-api.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5a768ad..55f3672 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -58,11 +58,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - id - type @@ -328,11 +328,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - '@context' responses: @@ -377,11 +377,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - '@context' responses: @@ -430,11 +430,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - '@context' responses: @@ -480,11 +480,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - '@context' responses: @@ -3190,17 +3190,17 @@ components: application/json+ld: schema: allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' - oneOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Relationship' - $ref: '#/components/schemas/GeoProperty' - $ref: '#/components/schemas/LanguageProperty' - - type: object - required: + - required: - '@context' - properties: - '@context': - $ref: '#/components/schemas/LdContext' EntityTemporal: content: application/json: -- GitLab From 7ad433c235b314dd279f2c7ac61942e78c18129f Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 11 Apr 2024 00:44:46 +0200 Subject: [PATCH 047/112] Show the @context field on top of the request and response bodies for the Context Information Consumption operations. Fixing issues with examples regarding /type /attributes endpoints for considering the @context inside the items section for EntityType[] and Attribute[] schemas. --- ngsi-ld-api.yaml | 50 ++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index db48d8d..bc00f86 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -153,11 +153,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - id - type @@ -222,11 +222,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Entity' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' - required: - id - type @@ -2248,16 +2248,16 @@ paths: '@context': $ref: '#/components/schemas/LdContext' - $ref: '#/components/schemas/EntityTypeList' - - allOf: - - type: object - required: - - '@context' - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - type: array - items: - $ref: '#/components/schemas/EntityType' + - type: array + items: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityType' '400': $ref: '#/components/responses/BadRequest' /types/{type}: @@ -2299,13 +2299,13 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/EntityTypeInfo' - type: object required: - '@context' properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTypeInfo' '400': $ref: '#/components/responses/BadRequest' '404': @@ -2367,23 +2367,23 @@ paths: schema: oneOf: - allOf: - - $ref: '#/components/schemas/AttributeList' - - type: object - required: - - '@context' - properties: - '@context': - $ref: '#/components/schemas/LdContext' - - allOf: - - type: array - items: - $ref: '#/components/schemas/Attribute' - type: object required: - '@context' properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/AttributeList' + - type: array + items: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Attribute' '400': $ref: '#/components/responses/BadRequest' /attributes/{attrId}: @@ -2424,13 +2424,13 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Attribute' - type: object required: - '@context' properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Attribute' '400': $ref: '#/components/responses/BadRequest' '404': -- GitLab From cbb5b5dfaa8c8a1b6781a1a8ddac11efb5e7f2fb Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 15 Apr 2024 10:56:48 +0200 Subject: [PATCH 048/112] Refactor payload body schema in ngsi-ld-api.yaml to include required '@context' property --- ngsi-ld-api.yaml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9fe0f97..e47c225 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2443,14 +2443,23 @@ paths: description: | Payload body in the request contains a JSON object that has a root node named @context, which represents a JSON-LD "local" context. - required: true content: application/json: schema: type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + required: + - '@context' application/json+ld: schema: type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + required: + - '@context' responses: '201': description: | -- GitLab From df86a34f650a438dd429926c647cb678d104e565 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 15 Apr 2024 11:34:44 +0200 Subject: [PATCH 049/112] Refactor ngsi-ld-api.yaml to include ngsildTenant parameter in createContext operation --- ngsi-ld-api.yaml | 64 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 21 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index e47c225..923bf80 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2439,6 +2439,8 @@ paths: With this operation, a client can ask the Broker to store the full content of a specific @context, by giving it to the Broker. operationId: createContext + parameters: + - $ref: '#/components/parameters/Headers.ngsildTenant' requestBody: description: | Payload body in the request contains a JSON object that has a root node named @context, @@ -2495,10 +2497,7 @@ paths: # Query params - $ref: '#/components/parameters/Query.details' - $ref: '#/components/parameters/Query.kind' - # Local Query param - - $ref: '#/components/parameters/Query.local' # Request headers - - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' responses: '200': @@ -2519,31 +2518,17 @@ paths: format: uri - type: array items: - type: object + $ref: '#/components/schemas/LdContextMetadata' application/json+ld: schema: oneOf: - type: array items: - allOf: - - type: string - format: uri - - type: object - required: - - '@context' - properties: - '@context': - $ref: '#/components/schemas/LdContext' + type: string + format: uri - type: array items: - allOf: - - type: object - - type: object - required: - - '@context' - properties: - '@context': - $ref: '#/components/schemas/LdContext' + $ref: '#/components/schemas/LdContextMetadata' '400': $ref: '#/components/responses/BadRequest' /jsonldContexts/{contextId}: @@ -4432,6 +4417,43 @@ components: - type: string format: uri - type: object + LdContextMetadata: + description: | + JSON object which represents information (metadata) + about an @context currently stored by the Broker as defined in 5.13.3.5. It contains information about the @context's + original URL (if any), its local identifier in the Broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"), + its creation timestamp, its expiry date (if "Cached"), and additional optional information. + type: array + items: + type: object + properties: + "URL": + type: string + format: uri + "localId": + type: string + format: uri + "kind": + type: string + enum: + - Cached + - Hosted + - ImplicitlyCreated + "timestamp": + type: string + format: date-time + "lastUsage": + type: string + format: date-time + "numberOfHits": + type: integer + "extraInfo": + type: object + required: + - "URL" + - "localId" + - "kind" + - "timestamp" NotUpdatedDetails: description: | 5.2.19 represents additional information provided by an implementation -- GitLab From b73c3fa93544565247adce32be682ccda4062792 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 15 Apr 2024 11:41:57 +0200 Subject: [PATCH 050/112] Refactor ngsi-ld-api.yaml to include required '@context' property in payload body schema --- ngsi-ld-api.yaml | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 923bf80..9216393 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2508,7 +2508,6 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' content: - # TODO: Output data described in 5.13.3.5, but not formally defined in tables. application/json: schema: oneOf: @@ -2549,10 +2548,7 @@ paths: - $ref: '#/components/parameters/Path.contextId' # Query params - $ref: '#/components/parameters/Query.details' - # Local Query param - - $ref: '#/components/parameters/Query.local' # Request headers - - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' responses: '200': @@ -2567,17 +2563,20 @@ paths: content: application/json: schema: - type: object + oneOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/LdContextMetadata' application/json+ld: schema: - allOf: + oneOf: - type: object - required: - - '@context' properties: '@context': - $ref: '#/components/schemas/LdContext' - - type: object + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/LdContextMetadata' '400': $ref: '#/components/responses/BadRequest' '404': -- GitLab From fdb7e67cc03aadce41f249fe916c8c0ccda2c899 Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 15 Apr 2024 11:44:23 +0200 Subject: [PATCH 051/112] Refactor ngsi-ld-api.yaml to remove unused parameters in the paths section --- ngsi-ld-api.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9216393..993a86d 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2603,10 +2603,7 @@ paths: - $ref: '#/components/parameters/Path.contextId' # Query params - $ref: '#/components/parameters/Query.reload' - # Local Query param - - $ref: '#/components/parameters/Query.local' # Request headers - - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' responses: '204': -- GitLab From 2f55b36333e30e3b0323619f00034c4e32e6c31e Mon Sep 17 00:00:00 2001 From: Marco Cavalli Date: Mon, 15 Apr 2024 11:57:32 +0200 Subject: [PATCH 052/112] Refactor error response descriptions in ngsi-ld-api.yaml --- ngsi-ld-api.yaml | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 993a86d..11b095b 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2580,9 +2580,19 @@ paths: '400': $ref: '#/components/responses/BadRequest' '404': - $ref: '#/components/responses/NotFound' + allOf: + $ref: '#/components/responses/NotFound' + description: | + It is used when a client provided an + @context identifier not known to the + system, see clause 6.3.2. '422': - $ref: '#/components/responses/Unprocessable' + allOf: + $ref: '#/components/responses/Unprocessable' + description: | + It is used when a client indicated an + @context of type "Cached", see + clause 6.3.2. delete: tags: - JSON-LD Context API @@ -2615,9 +2625,17 @@ paths: '400': $ref: '#/components/responses/BadRequest' '404': - $ref: '#/components/responses/NotFound' + allOf: + $ref: '#/components/responses/NotFound' + description: | + It is used when a client provided an + @context identifier not known to the + system, see clause 6.3.2. '503': - $ref: '#/components/responses/ServiceUnavailable' + allOf: + $ref: '#/components/responses/ServiceUnavailable' + description: | + It is used when re-downloading fails. components: headers: -- GitLab From 7fc88baa5325d6b04ee774f48b3bbb9936eaa785 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 12:44:42 +0200 Subject: [PATCH 053/112] Adding the required endpoint field within the CsourcRegistration data type for the 5.9.2 Register Context Source operation. Updating description for CsourceRegistration data type. --- ngsi-ld-api.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 704a431..34cfd62 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -636,6 +636,7 @@ paths: - required: - type - information + - endpoint application/json+ld: schema: allOf: @@ -647,6 +648,7 @@ paths: - required: - type - information + - endpoint - '@context' responses: '201': @@ -3573,7 +3575,7 @@ components: - triggerReason CsourceRegistration: description: | - 5.2.9 represents the data needed to register a new Context Source. + 5.2.9 This type represents the data needed to register a new Context Source. type: object properties: id: -- GitLab From 2c3f537a347e9857e9aac09bef1902c41fcea880 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 13:37:19 +0200 Subject: [PATCH 054/112] Show the @context field on top of the request and response bodies for the Registry API operations for Context Source Registration and Context Source Discovery. --- ngsi-ld-api.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 34cfd62..2aba4cc 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -640,11 +640,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/CsourceRegistration' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' - required: - type - information @@ -739,11 +739,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/CsourceRegistration' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' - required: - id - type @@ -791,11 +791,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/CsourceRegistration' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' - required: - id - type @@ -841,11 +841,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/CsourceRegistration' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' - required: - '@context' responses: @@ -4335,7 +4335,7 @@ components: - georel KeyValuePair: description: | - 5.2.22 represents the optional information that is required when contacting an endpoint for notifications. + 5.2.22 This datatype represents the optional information that is required when contacting an endpoint for notifications. type: object properties: key: -- GitLab From 1bcfa606d9bddaf8b3b5d99f8e40d751142072df Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 13:45:20 +0200 Subject: [PATCH 055/112] Deleting the 422 - Unprocessable response from 5.11.2 Create Context Source Registration Subscription operation. --- ngsi-ld-api.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index bc718d9..5181601 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1134,8 +1134,6 @@ paths: $ref: '#/components/responses/BadRequest' '409': $ref: '#/components/responses/Conflict' - '422': - $ref: '#/components/responses/Unprocessable' get: tags: - Context Source Registration Subscription -- GitLab From 95cee960f89eaabd72c63bc395262b21cbb3ad05 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 13:52:04 +0200 Subject: [PATCH 056/112] Update summary for 5.11.4 Retrieve Context Source Registration Subscription operation. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5181601..d484a7c 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1196,7 +1196,7 @@ paths: tags: - Context Source Registration Subscription summary: | - Retrieval of subscription to Csource registration by id + Csource registration subscription update by id description: | 5.11.4 Retrieve Context Source Registration Subscription. -- GitLab From ec5ba57e9283c94cf69c7ed3b714d33f22cd7198 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 14:00:28 +0200 Subject: [PATCH 057/112] Adding the Query.options.sysAttrs parameter for the 5.10.1 Retrieve Context Source Registration operation. --- ngsi-ld-api.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index d484a7c..49289c1 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -762,6 +762,8 @@ paths: This operation allows retrieving a specific context source registration from an NGSI-LD system. operationId: retrieveCSR parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' # Path params - $ref: '#/components/parameters/Path.registrationId' # Local Query param -- GitLab From 8a547e6bd277f90f1a8dc4af8930fb1ec80ccd52 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 14:11:59 +0200 Subject: [PATCH 058/112] Show the @context field on top of the request and response bodies for the Registry API operations for Context Source Registration Subscription. Fixing the tag for the 5.11.6 Delete Context Source Registration Subscription operation. --- ngsi-ld-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 49289c1..404afb7 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1181,11 +1181,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/Subscription' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' - required: - id - type @@ -1234,11 +1234,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Subscription' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' - required: - id - type @@ -1290,7 +1290,7 @@ paths: $ref: '#/components/responses/NotFound' delete: tags: - - Context Source Registration + - Context Source Registration Subscription summary: | Csource registration subscription deletion by id description: | -- GitLab From 3b9be336183aba5272fc42725a88a63544e91429 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 14:14:29 +0200 Subject: [PATCH 059/112] Adding the Query.options.sysAttrs parameter for the 5.11.4 Retrieve Context Source Registration Subscription operation. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 404afb7..f8a2404 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -762,8 +762,6 @@ paths: This operation allows retrieving a specific context source registration from an NGSI-LD system. operationId: retrieveCSR parameters: - # Query params - - $ref: '#/components/parameters/Query.options.sysAttrs' # Path params - $ref: '#/components/parameters/Path.registrationId' # Local Query param @@ -1205,6 +1203,8 @@ paths: This operation allows retrieving an existing Context Source Registration Subscription. operationId: retrieveCSRSubscription parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' # Path params - $ref: '#/components/parameters/Path.subscriptionId' # Local Query param -- GitLab From b6f84d84df9f37d3d7558d911b5fe707ee91ba72 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 19 Apr 2024 14:15:25 +0200 Subject: [PATCH 060/112] Adding the Query.options.sysAttrs parameter for the 5.10.1 Retrieve Context Source Registration operation. --- ngsi-ld-api.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2aba4cc..502db44 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -764,6 +764,8 @@ paths: This operation allows retrieving a specific context source registration from an NGSI-LD system. operationId: retrieveCSR parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' # Path params - $ref: '#/components/parameters/Path.registrationId' # Local Query param -- GitLab From 2d689c17020d03525bc79157a8e9366603e34b22 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sat, 20 Apr 2024 18:48:05 +0200 Subject: [PATCH 061/112] Updating the EntityTemporal data type schema to include the field id, type, and scope as well as the Entity data type schema (clause 5.2.4). Updating the description for the HTTP 201 response for the 5.6.11 Upsert Temporal Representation operation. --- ngsi-ld-api.yaml | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 55f3672..5f1f053 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1803,7 +1803,7 @@ paths: responses: '201': description: | - The HTTP response shall include a "Location" HTTP header that contains + Upon creation success, the HTTP response shall include a "Location" HTTP header that contains the resource URI of the created entity resource. headers: NGSILD-Tenant: @@ -3924,6 +3924,27 @@ components: the EntityTemporal by using the "Simplified Temporal Representation of an Entity", as defined in clause 4.5.9. properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. + oneOf: + - type: string + - type: array + items: + type: string + scope: + description: | + Scope. + oneOf: + - type: string + - type: array + items: + type: string location: description: | Default geospatial Property of an entity. See clause 4.7. -- GitLab From deabd978ff089025c01e51b47ef9f4cdc4619ff2 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sat, 20 Apr 2024 18:56:01 +0200 Subject: [PATCH 062/112] Updating description and operation Id for the 5.6.12 Add Attributes to Temporal Representation of an Entity operation --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5f1f053..b895f29 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1999,10 +1999,10 @@ paths: summary: | Temporal Representation of Entity Attribute instance addition description: | - 5.6.12 Append Entity Attributes. + 5.6.12 Add Attributes to Temporal Representation of an Entity. This operation allows modifying a Temporal Representation of an Entity by adding new Attribute instances. - operationId: appendAttrsTemporal + operationId: addAttrsTemporal parameters: # Path params - $ref: '#/components/parameters/Path.entityId' -- GitLab From 1b59e5a5c5a505823e88cef8da4fd2b4590e096d Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sat, 20 Apr 2024 19:00:40 +0200 Subject: [PATCH 063/112] Updating description for the 5.6.13 Delete Attributes from Temporal Representation of an Entity operation. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index b895f29..0145055 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2035,7 +2035,7 @@ paths: description: | 5.6.13 Delete Attributes from Temporal Representation of an Entity. - This operation allows deleting an NGSI-LD Entity's Attribute (Property or Relationship). + This operation allows deleting an Attribute (Property or Relationship) of the Temporal Representation of an Entity. The Attribute itself and all its children shall be deleted. operationId: deleteAttrsTemporal parameters: -- GitLab From ce78da1c2fd1ff24c21cfb2a3292339fbd55e7f6 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sat, 20 Apr 2024 19:08:37 +0200 Subject: [PATCH 064/112] Updating the descriptrion fo the request body for the 5.6.14 Partial Update Attribute instance in Temporal Representation of an Entity operation. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 0145055..197e6e1 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2002,7 +2002,7 @@ paths: 5.6.12 Add Attributes to Temporal Representation of an Entity. This operation allows modifying a Temporal Representation of an Entity by adding new Attribute instances. - operationId: addAttrsTemporal + operationId: appendAttrsTemporal parameters: # Path params - $ref: '#/components/parameters/Path.entityId' @@ -2087,7 +2087,7 @@ paths: - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' requestBody: - description: Entity Fragment containing the elements of the attribute to be updated. + description: EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced. $ref: '#/components/requestBodies/EntityTemporalFragment' responses: '204': -- GitLab From c75e6cb4b78f5d4442ff0e3de796e1a8aac77485 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:06:45 +0200 Subject: [PATCH 065/112] Adding the default value of observedAt within th timeproperty query parameter as defined by 5.7.3 Retrieve Temporal Evolution of an Entity and 5.7.4 Query Temporal Evolution of Entities operations. --- ngsi-ld-api.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index bc00f86..2c9c82f 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3157,6 +3157,7 @@ components: - createdAt - modifiedAt - deletedAt + default: observedAt required: false Query.timerel: name: timerel @@ -5074,6 +5075,7 @@ components: - createdAt - modifiedAt - deletedAt + default: observedAt required: - timerel - timeAt -- GitLab From 69bf0a2dabd5f575547c96c5ae6efef7b40431eb Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:10:30 +0200 Subject: [PATCH 066/112] Adding the System Attributes options parameter for 5.7.4 Query Temporal Evolution of Entities operation as deduced from clause 6.3.11. --- ngsi-ld-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2c9c82f..0313fc2 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1851,6 +1851,7 @@ paths: - $ref: '#/components/parameters/Query.scopeQ' - $ref: '#/components/parameters/Query.limit' - $ref: '#/components/parameters/Query.options.temporal' + - $ref: '#/components/parameters/Query.options.sysAttrs' # Local Query param - $ref: '#/components/parameters/Query.local' # Request headers -- GitLab From 433f35d20827c74facb9c8140a322fd77ed780dd Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:12:43 +0200 Subject: [PATCH 067/112] Adding the alternative keyword simplified as synonym of keyword keyValues, as mandated from clause 6.3.7. --- ngsi-ld-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 0313fc2..9f08bd9 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3340,6 +3340,7 @@ components: - normalized - concise - keyValues + - simplified options.sysAttrs: description: 6.3.11 Including system generated attributes. type: string -- GitLab From 2aaadaf25c48e29e04c2ab02ca614b95f6972e9a Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:26:13 +0200 Subject: [PATCH 068/112] Deleting scopeQ and limit extra parameters and skipping the required: true argument for timerel and timeAt query parameters from 5.7.3 Retrieve Temporal Evolution of an Entity operation. --- ngsi-ld-api.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9f08bd9..3cb2a6d 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1911,16 +1911,12 @@ paths: - $ref: '#/components/parameters/Query.attrs' - $ref: '#/components/parameters/Query.timeproperty' - $ref: '#/components/parameters/Query.timerel' - required: true - $ref: '#/components/parameters/Query.timeAt' - required: true - $ref: '#/components/parameters/Query.endTimeAt' - $ref: '#/components/parameters/Query.lastN' - $ref: '#/components/parameters/Query.lang' - $ref: '#/components/parameters/Query.aggrMethods' - $ref: '#/components/parameters/Query.aggrPeriodDuration' - - $ref: '#/components/parameters/Query.scopeQ' - - $ref: '#/components/parameters/Query.limit' - $ref: '#/components/parameters/Query.options.temporal' # Local Query param - $ref: '#/components/parameters/Query.local' -- GitLab From c65159caf98804796d51e89bacf9a7327da37c4d Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:27:11 +0200 Subject: [PATCH 069/112] Adding the System Attributes options parameter for 5.7.3 Retrieve Temporal Evolution of an Entity operation as deduced from clause 6.3.11. --- ngsi-ld-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 3cb2a6d..0094491 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1918,6 +1918,7 @@ paths: - $ref: '#/components/parameters/Query.aggrMethods' - $ref: '#/components/parameters/Query.aggrPeriodDuration' - $ref: '#/components/parameters/Query.options.temporal' + - $ref: '#/components/parameters/Query.options.sysAttrs' # Local Query param - $ref: '#/components/parameters/Query.local' # Request headers -- GitLab From df3a4390ebb3567f114f29da0841ff4c92b7228c Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:33:03 +0200 Subject: [PATCH 070/112] Skipping the uri format for attrs query paramenter. --- ngsi-ld-api.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 0094491..9e54729 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2808,7 +2808,6 @@ components: type: array items: type: string - format: uri required: false Query.coordinates: name: coordinates -- GitLab From 2069591ea833784ad6ae6a6b242a1d023da83dd0 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:35:25 +0200 Subject: [PATCH 071/112] Updating the minimum for lastN query argument to 1. It needs to be a positive integer. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9e54729..a9a7476 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3007,7 +3007,7 @@ components: explode: true schema: type: integer - minimum: 0 + minimum: 1 required: false Query.limit: name: limit -- GitLab From 1c669c74cfa213ba99932e9921ab8e92f4cf8484 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 16:40:07 +0200 Subject: [PATCH 072/112] Adding the default value of 0 for aggrPeriodDuration query parameter as mandated from 5.7.4 Query Temporal Evolution of Entities and 5.7.3 Retrieve Temporal Evolution of an Entity operations. --- ngsi-ld-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index a9a7476..7ffc2db 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -2794,6 +2794,7 @@ components: explode: false schema: type: string + default: '0' required: false Query.attrs: name: attrs -- GitLab From 73c21f815738ae8a540d0980077bfbad0ca0dff6 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 17:07:16 +0200 Subject: [PATCH 073/112] Show the @context field on top of the request and response/request bodies for the Registry API operations for Temporal Context Information Consumption operations. --- ngsi-ld-api.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 7ffc2db..59bbef6 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1879,11 +1879,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/EntityTemporal' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' - required: - id - type @@ -1943,11 +1943,11 @@ paths: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/EntityTemporal' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' - required: - id - type @@ -2171,11 +2171,11 @@ paths: type: array items: allOf: - - $ref: '#/components/schemas/EntityTemporal' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' - required: - id - type @@ -3263,11 +3263,11 @@ components: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Query.temporal' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Query.temporal' - required: - '@context' Subscription: -- GitLab From dc044afa61f08e3d2862e69d2b257a53000c9ce3 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 21 Apr 2024 17:14:47 +0200 Subject: [PATCH 074/112] Show the @context field on top of the request and response/request bodies for the Registry API operations for Temporal Context Information Provision operations. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 197e6e1..caff0d0 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3212,11 +3212,11 @@ components: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/EntityTemporal' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' - required: - id - type @@ -3229,11 +3229,11 @@ components: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/EntityTemporal' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' - required: - '@context' Query: -- GitLab From 0d47419e155897e8da11054bb0695508d31c32a6 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 22 Apr 2024 01:31:07 +0200 Subject: [PATCH 075/112] Including possible values for geoproperty query parameter as mandated by clause 4.7. --- ngsi-ld-api.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 59bbef6..5045be9 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -189,7 +189,6 @@ paths: - $ref: '#/components/parameters/Path.entityId' # Query params - $ref: '#/components/parameters/Query.attrs' - # REVIEW GeoProperty - $ref: '#/components/parameters/Query.geometryProperty' # REVIEW Options entities - $ref: '#/components/parameters/Query.lang' @@ -2846,7 +2845,6 @@ components: schema: type: string required: false - # REVIEW Query.datasetId: name: datasetId in: query @@ -2913,7 +2911,6 @@ components: type: string format: pattern required: false - # REVIEW (5.7.1 y 6.4.3/6.5.3) Query.geometryProperty: name: geometryProperty in: query @@ -2942,7 +2939,6 @@ components: - Polygon - MultiPolygon required: false - # REVIEW (5.7.1 y 6.4.3/6.5.3) Query.geoproperty: name: geoproperty in: query @@ -2953,6 +2949,11 @@ components: explode: true schema: type: string + enum: + - location + - observationSpace + - operationSpace + default: location required: false Query.georel: name: georel -- GitLab From 17bc03d446dd388dfe13dec698f6159c1ea55d3f Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 22 Apr 2024 01:33:10 +0200 Subject: [PATCH 076/112] Including description for sysAttrs options parameter. --- ngsi-ld-api.yaml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5045be9..aaffc5f 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3319,7 +3319,9 @@ components: - noOverwrite options.representation: description: | - 6.3.7 Representation of Entities. When its value includes the keyword "normalized", a normalized + 6.3.7 Representation of Entities. + + When its value includes the keyword "normalized", a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2 and 4.5.18.2. @@ -3340,7 +3342,13 @@ components: - keyValues - simplified options.sysAttrs: - description: 6.3.11 Including system generated attributes. + description: | + 6.3.11 Including system generated attributes. + + When its value includes the keyword "sysAttrs", a representation of NGSI-LD Elements shall be + provided so that the system generated attributes createdAt, modifiedAt are included in the response + payload body. In the case of temporal representations, also the system generated attribute deletedAt + is included, if the NGSI-LD Element has been deleted. type: string enum: - sysAttrs -- GitLab From 820261049bffa1d5403e0fcd2b71e681487da132 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 16 May 2024 21:41:55 +0200 Subject: [PATCH 077/112] Deleting some review comments already resolved on the NGSI-LD OAS. --- ngsi-ld-api.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index aaffc5f..8496ba7 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -190,7 +190,6 @@ paths: # Query params - $ref: '#/components/parameters/Query.attrs' - $ref: '#/components/parameters/Query.geometryProperty' - # REVIEW Options entities - $ref: '#/components/parameters/Query.lang' - $ref: '#/components/parameters/Query.options.entities' # Local Query param @@ -3046,7 +3045,6 @@ components: type: string format: date-time required: false - # REVIEW Query.options.entities: name: options in: query -- GitLab From 8b38947fb56d8adb99ef80f537463dc468697623 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 17 May 2024 00:12:15 +0200 Subject: [PATCH 078/112] Updating description for 5.7.2 Query Entity (batch entity queries only) operation. --- ngsi-ld-api.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 8496ba7..a881a3f 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1653,7 +1653,9 @@ paths: summary: | Query entities based on POST description: | - 5.7.2 Query Entities (batch entity queries only). + 5.7.2 Query Entity (batch entity queries only). + + This operation allows querying an NGSI-LD system. operationId: queryBatch parameters: # Local Query param -- GitLab From 82741bacb7395ed08b91dfce37d7a4aa8f0efce4 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 17 May 2024 00:15:20 +0200 Subject: [PATCH 079/112] Updating description for 5.7.2 Query Entity (batch entity queries only) operation. --- ngsi-ld-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 635bcb5..a43ee56 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1635,7 +1635,7 @@ paths: summary: | Query entities based on POST description: | - 5.7.2 Query Entity. + 5.7.2 Query Entity (batch entity queries only). This operation allows querying an NGSI-LD system. operationId: queryBatch -- GitLab From 322364d773766508dbc76e4341a900b45f28ed8d Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 17 May 2024 00:26:47 +0200 Subject: [PATCH 080/112] Reviewing and fixing issues regarding schemas, headers and parameters sections within the NGSI-LD OAS 1.6.1. --- ngsi-ld-api.yaml | 169 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 114 insertions(+), 55 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index aaffc5f..391c301 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -190,7 +190,6 @@ paths: # Query params - $ref: '#/components/parameters/Query.attrs' - $ref: '#/components/parameters/Query.geometryProperty' - # REVIEW Options entities - $ref: '#/components/parameters/Query.lang' - $ref: '#/components/parameters/Query.options.entities' # Local Query param @@ -2643,7 +2642,7 @@ components: type: string NGSILD-Results-Count: description: | - 6.3.13 Counting number of results + 6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned. schema: type: integer NGSILD-Tenant: @@ -2681,14 +2680,6 @@ components: schema: type: string format: uri - Headers.ngsildCount: - name: NGSILD-Results-Count - in: header - description: | - 6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned. - explode: true - schema: - type: integer Headers.ngsildTenant: name: NGSILD-Tenant in: header @@ -2706,6 +2697,7 @@ components: given that the latter is part of the JSON-LD @context provided. schema: type: string + format: uri required: true Path.contextId: name: contextId @@ -2715,6 +2707,7 @@ components: this can also be the original URL the Broker downloaded the @context from. schema: type: string + format: uri required: true Path.entityId: name: entityId @@ -2757,6 +2750,7 @@ components: given that the latter is part of the JSON-LD @context provided. schema: type: string + format: uri required: true Query.aggrMethods: name: aggrMethods @@ -2822,6 +2816,7 @@ components: - $ref: '#/components/schemas/Geometry.position' - $ref: '#/components/schemas/Geometry.positionArray' - $ref: '#/components/schemas/Geometry.lineString' + - $ref: '#/components/schemas/Geometry.linearRing' - $ref: '#/components/schemas/Geometry.polygon' required: false Query.count: @@ -2915,6 +2910,10 @@ components: name: geometryProperty in: query description: | + 4.5.16.1 Top-level "geometry" field selection algorithm. + A parameter of the request (named "geometryProperty") may be used to indicate the name of the GeoProperty to be selected. + If this parameter is not present, then the default name of "location" shall be used. + In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field. style: form @@ -2974,7 +2973,7 @@ components: - contains - overlaps - type: string - pattern: ^near;((maxDistance==\\d+)|(minDistance==\\d+))$ + pattern: ^near;((maxDistance==\\d+)|(minDistance==\\d+))$ required: false Query.kind: name: kind @@ -3046,7 +3045,6 @@ components: type: string format: date-time required: false - # REVIEW Query.options.entities: name: options in: query @@ -3279,7 +3277,7 @@ components: - $ref: '#/components/schemas/Subscription' - required: - type - - entities + - notification application/json+ld: schema: allOf: @@ -3290,6 +3288,7 @@ components: $ref: '#/components/schemas/LdContext' - required: - type + - notification - '@context' SubscriptionFragment: content: @@ -3313,7 +3312,9 @@ components: # Beginning of Options parameters # options.noOverwrite: - description: Indicates that no attribute overwrite shall be performed. + description: | + 6.16.3 For POST method associated to the operation "Batch Entity Update", the "noOvevwrite" + options query parameter indicates that no attribute overwrite shall be performed. type: string enum: - noOverwrite @@ -3378,6 +3379,7 @@ components: enum: - replace - update + default: replace # # End of Options parameters ### @@ -3389,19 +3391,23 @@ components: description: | Is defined as the temporal Property at which the Entity, Property or Relationship was entered into an NGSI-LD system. + + Entity creation timestamp. See clause 4.8. type: string format: date-time ModifiedAt: description: | Is defined as the temporal Property at which the Entity, Property or Relationship was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value. + + Entity last modification timestamp. See clause 4.8. type: string format: date-time DeletedAt: description: | Is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system. - Entity deletion timestamp. See clause 4.8 It is only used in notifications reporting deletions and in the + Entity deletion timestamp. See clause 4.8. It is only used in notifications reporting deletions and in the Temporal Representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8) and LanguageProperties (clause 5.2.32). type: string @@ -3415,7 +3421,6 @@ components: # # End of 4.8 Temporal Properties ### - Attribute: description: | 5.2.28 This type represents the data needed to define the attribute information. @@ -3487,7 +3492,7 @@ components: - attributeList BatchEntityError: description: | - 5.2.17 represents an error raised (associated to a particular Entity) during + 5.2.17 This datatype represents an error raised (associated to a particular Entity) during the execution of a batch or distributed operation. type: object properties: @@ -3510,7 +3515,7 @@ components: - error BatchOperationResult: description: | - 5.2.16 represents the result of a batch operation. + 5.2.16 The datatype represents the result of a batch operation. type: object properties: success: @@ -3595,7 +3600,7 @@ components: - triggerReason CsourceRegistration: description: | - 5.2.9 represents the data needed to register a new Context Source. + 5.2.9 This type represents the data needed to register a new Context Source. type: object properties: id: @@ -3658,8 +3663,16 @@ components: Location for which the Context Source may be able to provide information. $ref: '#/components/schemas/Geometry' observationSpace: + description: | + Geographic location that includes the observation spaces of all entities as specified by their + respective observationSpace GeoProperty for which the Context Source may be able to provide + information. $ref: '#/components/schemas/Geometry' operationSpace: + description: | + Geographic location that includes the operation spaces of all entities as specified by their + respective operationSpace GeoProperty for which the Context Source may be able to provide + information. $ref: '#/components/schemas/Geometry' expiresAt: description: | @@ -3697,6 +3710,7 @@ components: - exclusive - redirect - auxiliary + default: inclusive operations: description: | The definition limited subset of API operations supported by the registered Context Source. @@ -3766,7 +3780,7 @@ components: $ref: '#/components/schemas/AnyValue' DateTimeValue: description: | - Date representation as mandated by C.6 "Date Representation" + Date representation as mandated by C.6 "Date Representation". type: object properties: '@type': @@ -3782,7 +3796,7 @@ components: - '@value' Endpoint: description: | - 5.2.15 represents the parameters that are required in order to define an endpoint for notifications. + 5.2.15 This datatype represents the parameters that are required in order to define an endpoint for notifications. type: object properties: uri: @@ -3802,15 +3816,17 @@ components: timeout: description: | Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. - The NGSI-LD system can override this value. This only applies if the binding - protocol always returns a response. + The NGSI-LD system can override this value. This only applies if the binding protocol always returns a + response. type: number + minimum: 1 cooldown: description: | Once a failure has occurred, minimum period of time in milliseconds which shall elapse before attempting to make a subsequent notification to the same endpoint after failure. If requests are received before the cooldown period has expired, no notification is sent. type: number + minimum: 1 receiverInfo: description: | Generic {key, value} array to convey optional information to the receiver. @@ -3827,7 +3843,7 @@ components: - uri Entity: description: | - NGSI-LD Entity (see 5.4). + 5.2.4 NGSI-LD Entity. type: object properties: id: @@ -3856,8 +3872,12 @@ components: Default geospatial Property of an entity. See clause 4.7. $ref: '#/components/schemas/GeoProperty' observationSpace: + description: | + See clause 4.7. $ref: '#/components/schemas/GeoProperty' operationSpace: + description: | + See clause 4.7. $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated createdAt: @@ -3884,8 +3904,8 @@ components: $ref: '#/components/schemas/Relationship' EntityInfo: description: | - 5.2.8 represents what Entities, Entity Types or group of Entity ids - (as a regular expression pattern mandated by IEEE 1003.2TM [11]) can be provided (by Context Sources). + 5.2.8 This type represents what Entities, Entity Types or group of Entity ids + (as a regular expression pattern mandated by IEEE 1003.2TM) can be provided (by Context Sources). type: object properties: id: @@ -3911,7 +3931,7 @@ components: EntitySelector: description: | 5.2.33 This type selects which entity or group of entities are queried or subscribed to by Context Consumers. - `id` takes precedence over `idPattern`. + The `id` takes precedence over `idPattern`. type: object properties: id: @@ -3923,6 +3943,7 @@ components: description: | A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. type: string + format: pattern type: description: | Selector of Entity Type(s). @@ -3938,13 +3959,38 @@ components: the EntityTemporal by using the "Simplified Temporal Representation of an Entity", as defined in clause 4.5.9. properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. + oneOf: + - type: string + - type: array + items: + type: string + scope: + description: | + Scope. + oneOf: + - type: string + - type: array + items: + type: string location: description: | Default geospatial Property of an entity. See clause 4.7. $ref: '#/components/schemas/GeoProperty' observationSpace: + description: | + See clause 4.7. $ref: '#/components/schemas/GeoProperty' operationSpace: + description: | + See clause 4.7. $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated createdAt: @@ -4096,7 +4142,7 @@ components: '@context': description: | JSON-LD @context. This field is only present if requested in the payload by - the HTTP Prefer Header (IETF RFC 724). + the HTTP Prefer Header (IETF RFC 7240). $ref: '#/components/schemas/LdContext' required: - id @@ -4124,7 +4170,7 @@ components: '@context': description: | JSON-LD @context. This field is only present if requested in the payload - by the HTTP Prefer Header (IETF RFC 724). + by the HTTP Prefer Header (IETF RFC 7240). $ref: '#/components/schemas/LdContext' required: - type @@ -4171,7 +4217,7 @@ components: A single position. type: array minItems: 2 - maxItems: 2 + maxItems: 3 items: type: number additionalProperties: false @@ -4189,7 +4235,7 @@ components: - minItems: 2 Geometry.linearRing: description: | - An array of four positions where the first equals the last. + An array of four positions where the first equals the last (i.e., a closed LineString). allOf: - $ref: '#/components/schemas/Geometry.positionArray' - minItems: 4 @@ -4259,7 +4305,7 @@ components: $ref: '#/components/schemas/Geometry.lineString' Geometry: description: | - A valid GeoJSON geometry object. + A valid GeoJSON geometry object (as mandated by RFC7946). oneOf: - $ref: '#/components/schemas/Geometry.Point' - $ref: '#/components/schemas/Geometry.MultiPoint' @@ -4283,15 +4329,19 @@ components: - GeoProperty default: GeoProperty value: + description: | + Geolocation encoded as GeoJSON. As mandated by clause 4.7. $ref: '#/components/schemas/Geometry' observedAt: + description: | + Timestamp. See clause 4.8. $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. type: string format: uri - # Clause 5.2.2 Common members. System-generated + # Clause 5.2.2 Common members. System-generated createdAt: allOf: - $ref: '#/components/schemas/CreatedAt' @@ -4323,9 +4373,10 @@ components: $ref: '#/components/schemas/Relationship' GeoQuery: description: | - 5.2.13 represents a geoquery used for Subscriptions. + 5.2.13 This datatype represents a geoquery used for Subscriptions. type: object properties: + # Could be of Geometry schema type geometry: description: | Type of the reference geometry. @@ -4386,6 +4437,8 @@ components: String Property Values defined in multiple natural languages. type: object observedAt: + description: | + Timestamp. See clause 4.8. $ref: '#/components/schemas/ObservedAt' datasetId: description: | @@ -4414,7 +4467,8 @@ components: readOnly: true previousLanguageMap: description: | - Previous Language Property languageMap. Only used in notifications. + Previous Language Property languageMap. Only used in notifications, if the showChanges + option is explicitly requested. type: object readOnly: true additionalProperties: @@ -4446,7 +4500,7 @@ components: - type: object NotUpdatedDetails: description: | - 5.2.19 represents additional information provided by an implementation + 5.2.19 This datatype represents additional information provided by an implementation when an Attribute update did not happen. type: object properties: @@ -4516,7 +4570,7 @@ components: - data NotificationParams: description: | - 5.2.14 represents the parameters that allow to convey the details of a notification. + 5.2.14 This datatype represents the parameters that allow to convey the details of a notification. type: object properties: attributes: @@ -4532,6 +4586,7 @@ components: If true, the system generated attributes createdAt and modifiedAt are included in the response payload body, in the case of a deletion also deletedAt. type: boolean + default: false format: description: | Conveys the representation format of the entities delivered at notification time. @@ -4548,6 +4603,7 @@ components: This requires that it exists, i.e. in case of modifications and deletions, but not in the case of creations. showChanges cannot be true in case format is "keyValues". type: boolean + default: false endpoint: description: | Notification endpoint details. @@ -4565,13 +4621,13 @@ components: Number of times that the notification has been sent. Provided by the system when querying the details of a subscription. type: number - minimum: 0 + minimum: 1 timesFailed: description: | Number of times an unsuccessful response (or timeout) has been received when deliverying the notification. Provided by the system when querying the details of a subscription. type: number - minimum: 0 + minimum: 1 lastNotification: description: | Timestamp corresponding to the instant when the last notification has been sent. @@ -4599,17 +4655,17 @@ components: ProblemDetails: description: | The definition of the general "ProblemDetails" data structure from - IETF RFC 7807 [19] is reproduced inthis structure. Compared to the - general framework defined in IETF RFC 7807 [19], the "status" and + IETF RFC 7807 is reproduced inthis structure. Compared to the + general framework defined in IETF RFC 7807, the "status" and "detail" attributes are mandated to be included by the present document, to ensure that the response contains additional textual information about - an error. IETF RFC 7807 [19] foresees extensibility of the + an error. IETF RFC 7807 foresees extensibility of the "ProblemDetails" type. It is possible that particular APIs in the present document, or particular implementations, define extensions to define additional attributes that provide more information about the error. The description column only provides some explanation of the meaning to Facilitate understanding of the design. For a full description, see - IETF RFC 7807 [19]. + IETF RFC 7807. type: object required: - status @@ -4617,7 +4673,7 @@ components: properties: type: description: | - A URI reference according to IETF RFC 3986 [5] that identifies the + A URI reference according to IETF RFC 3986 that identifies the problem type. It is encouraged that the URI provides human-readable documentation for the problem (e.g. using HTML) when dereferenced. When this member is not present, its value is assumed to be @@ -4674,11 +4730,9 @@ components: - $ref: '#/components/schemas/DateTimeValue' - $ref: '#/components/schemas/AnyValue' observedAt: - $ref: '#/components/schemas/ObservedAt' description: | Timestamp. See clause 4.8. - type: string - format: date-time + $ref: '#/components/schemas/ObservedAt' unitCode: description: | Property Value's unit code. @@ -4710,7 +4764,8 @@ components: readOnly: true previousValue: description: | - Previous Property value. Only used in notifications. + Previous Property value. Only used in notifications, if the showChanges + option is explicitly requested. allOf: - oneOf: - $ref: '#/components/schemas/DateTimeValue' @@ -4766,10 +4821,10 @@ components: Context source filter that shall be matched by Context Source Registrations describing Context Sources to be used for retrieving Entities. type: string - temporalQ: - description: | - Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). - $ref: '#/components/schemas/TemporalQuery' + #temporalQ: + # description: | + # Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). + # $ref: '#/components/schemas/TemporalQuery' scopeQ: description: Scope query. type: string @@ -4867,6 +4922,8 @@ components: type: string format: uri observedAt: + description: | + Timestamp. See clause 4.8. $ref: '#/components/schemas/ObservedAt' datasetId: description: | @@ -4895,7 +4952,8 @@ components: readOnly: true previousObject: description: | - Previous Relationship's target object. Only used in notifications. + Previous Relationship's target object. Only used in notifications, if the showChanges + option is explicitly requested. type: string format: uri readOnly: true @@ -4915,7 +4973,7 @@ components: - $ref: '#/components/schemas/Subscription.Periodic' Subscription.Common: description: | - 5.2.12 represents a Context Subscription. + 5.2.12 This datatype represents a Context Subscription. type: object properties: id: @@ -4978,6 +5036,7 @@ components: true indicates that the Subscription is under operation. false indicates that the subscription is paused and notifications shall not be delivered. type: boolean + default: true notification: description: | Notification details. @@ -5106,7 +5165,7 @@ components: - startAt UpdateResult: description: | - 5.2.18 represents the result of Attribute update (append or update) operations + 5.2.18 This datatype represents the result of Attribute update (append or update) operations in the NGSI-LD API regardless of whether local or distributed. type: object properties: -- GitLab From 5ced645a16451387e1feace54693f4255e6c1237 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Fri, 17 May 2024 00:44:14 +0200 Subject: [PATCH 081/112] Adding reference to GeoProperty and LanguageProperty within additionalProperties of Entity schema. --- ngsi-ld-api.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 391c301..f1d3f7f 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3902,6 +3902,14 @@ components: - type: array items: $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - type: array + items: + $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - type: array + items: + $ref: '#/components/schemas/LanguageProperty' EntityInfo: description: | 5.2.8 This type represents what Entities, Entity Types or group of Entity ids -- GitLab From 4b18cfbbcc266b434dff2cc75ad52c0295ae5ca5 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 26 May 2024 19:12:57 +0200 Subject: [PATCH 082/112] Recovering SubscriptionFragment Request Body definition. Generating a new Path common schema for URI data type in path parameters. Generating a new SystemGeneratedAttributes for grouping subschemas of system-generated temporal attributes: createdAt, modifiedAt, and deletedAt, and updating references to it. Keeping NGSILD-Warning header only for HTTP GET operations performed over the resources /entities and /entities/{entity-id}. --- ngsi-ld-api.yaml | 209 ++++++++++++++--------------------------------- 1 file changed, 62 insertions(+), 147 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 89dfade..5db7a29 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -780,9 +780,6 @@ paths: '200': description: | A response body containing the JSON-LD representation of the target subscription. - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -808,14 +805,8 @@ paths: - endpoint - '@context' '400': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '404': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' patch: tags: @@ -1013,8 +1004,6 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1038,14 +1027,8 @@ paths: - notification - '@context' '400': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '404': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' patch: tags: @@ -1068,7 +1051,7 @@ paths: requestBody: description: | Subscription Fragment including id, type and any other subscription field to be changed. - $ref: '#/components/requestBodies/Subscription' + $ref: '#/components/requestBodies/SubscriptionFragment' responses: '204': description: | @@ -1231,8 +1214,6 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1256,14 +1237,8 @@ paths: - notification - '@context' '400': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '404': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' patch: tags: @@ -1287,7 +1262,7 @@ paths: description: | Subscription Fragment including id, type and any other context source registration subscription field to be changed. - $ref: '#/components/requestBodies/Subscription' + $ref: '#/components/requestBodies/SubscriptionFragment' responses: '204': description: | @@ -1388,8 +1363,7 @@ paths: items: type: string '207': - allOf: - - $ref: '#/components/responses/MultiStatus.BatchOperationResult' + $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. @@ -1913,9 +1887,6 @@ paths: - type - '@context' '400': - headers: - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' /temporal/entities/{entityId}: get: @@ -2730,8 +2701,7 @@ components: The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Path.contextId: name: contextId @@ -2740,40 +2710,35 @@ components: Local identifier of the @context to be managed (served or deleted). For @contexts of kind "Cached" this can also be the original URL the Broker downloaded the @context from. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Path.entityId: name: entityId in: path description: Id (URI) of the entity to be retrieved. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Path.instanceId: name: instanceId in: path description: Id (URI) identifying a particular Attribute instance. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Path.registrationId: name: registrationId in: path description: Id (URI) of the context source registration. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Path.subscriptionId: name: subscriptionId in: path description: Id (URI) of the concerned subscription. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Path.type: name: type @@ -2783,8 +2748,7 @@ components: The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided. schema: - type: string - format: uri + $ref: '#/components/schemas/Path' required: true Query.aggrMethods: name: aggrMethods @@ -3317,11 +3281,11 @@ components: application/json+ld: schema: allOf: - - $ref: '#/components/schemas/Subscription' - type: object properties: '@context': $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' - required: - '@context' schemas: @@ -3406,9 +3370,28 @@ components: # # Beginning of 4.8 Temporal Properties # + SystemGeneratedAttributes: + description: | + 5.2.2 Common members. + + For grouping the subschemas of system-generated temporal attributes: createdAt, modifiedAt, and deletedAt. + type: object + properties: + createdAt: + allOf: + - $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + allOf: + - $ref: '#/components/schemas/DeletedAt' + readOnly: true CreatedAt: description: | - Is defined as the temporal Property at which the Entity, Property or + It is defined as the temporal Property at which the Entity, Property or Relationship was entered into an NGSI-LD system. Entity creation timestamp. See clause 4.8. @@ -3416,7 +3399,7 @@ components: format: date-time ModifiedAt: description: | - Is defined as the temporal Property at which the Entity, Property or Relationship + It is defined as the temporal Property at which the Entity, Property or Relationship was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value. Entity last modification timestamp. See clause 4.8. @@ -3424,7 +3407,7 @@ components: format: date-time DeletedAt: description: | - Is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system. + It is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system. Entity deletion timestamp. See clause 4.8. It is only used in notifications reporting deletions and in the Temporal Representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8) @@ -3433,7 +3416,7 @@ components: format: date-time ObservedAt: description: | - Is defined as the temporal Property at which a certain Property or Relationship became valid or was observed. + It is defined as the temporal Property at which a certain Property or Relationship became valid or was observed. For example, a temperature Value was measured by the sensor at this point in time. type: string format: date-time @@ -3748,19 +3731,10 @@ components: Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. $ref: '#/components/schemas/RegistrationManagementInfo' - # Clause 5.2.2 Common members. System-generated - createdAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: - allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' status: description: | Read-only. Status of the Registration. It shall be "ok" if the last attempt to perform a distributed @@ -3898,19 +3872,10 @@ components: description: | See clause 4.7. $ref: '#/components/schemas/GeoProperty' - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' additionalProperties: oneOf: - $ref: '#/components/schemas/Property' @@ -4019,19 +3984,10 @@ components: description: | See clause 4.7. $ref: '#/components/schemas/GeoProperty' - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' additionalProperties: oneOf: - type: array @@ -4368,19 +4324,10 @@ components: It allows identifying a set or group of property values. type: string format: uri - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, @@ -4472,19 +4419,10 @@ components: It allows identifying a set or group of property values. type: string format: uri - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, @@ -4713,6 +4651,10 @@ components: format: date-time required: - endpoint + Path: + description: Common schema for URI data type in path parameters. + type: string + format: uri ###### # "ProblemDetails" schema from ETSI NFV OAS (BEGIN) # @@ -4806,19 +4748,10 @@ components: It allows identifying a set or group of property values. type: string format: uri - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, @@ -4994,19 +4927,10 @@ components: It allows identifying a set or group of target relationship objects. type: string format: uri - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: - allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Relationship instance @@ -5123,19 +5047,10 @@ components: description: | Language filter to be applied to the query (clause 4.15). type: string - # Clause 5.2.2 Common members. System-generated - createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: allOf: - - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: - allOf: - - $ref: '#/components/schemas/DeletedAt' - readOnly: true + - $ref: '#/components/schemas/SystemGeneratedAttributes' status: description: | Read-only. Provided by the system when querying the details of a subscription. -- GitLab From 84ebe49ca4dc79d31b28366e1de6e1d588f0f871 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 26 May 2024 19:19:42 +0200 Subject: [PATCH 083/112] Updating title and description within the openapi section of NGSI-LD OAS v1.6.1. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5db7a29..cd14754 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1,8 +1,8 @@ openapi: 3.0.3 info: - title: NGSI-LD API + title: NGSI-LD OAS version: 1.6.1 - description: ETSI GS CIM 009 V1.6.1 cross-cutting Context Information Management (CIM); NGSI-LD API. + description: OpenAPI Specification for NGSI-LD API. contact: url: https://www.etsi.org/committee/cim license: -- GitLab From e5c386e28312b25f33d45ccc65ee261711dbb4b1 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 26 May 2024 19:40:56 +0200 Subject: [PATCH 084/112] Removing allOf keyword for references to additional components when there are already descriptions. Including and description fields together despite the sibling issue in OAS 3.0.3. --- ngsi-ld-api.yaml | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index cd14754..38af450 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1453,8 +1453,6 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': - allOf: - - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully created or updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. @@ -1471,6 +1469,7 @@ paths: is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/update: @@ -1527,8 +1526,6 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': - allOf: - - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully updated, a response @@ -1558,6 +1555,7 @@ paths: Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/delete: @@ -1594,8 +1592,6 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': - allOf: - - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If some or all of the entities have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned @@ -1613,6 +1609,7 @@ paths: fails or times out, see clause 6.3.17. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /entityOperations/query: @@ -1750,8 +1747,6 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': - allOf: - - $ref: '#/components/responses/MultiStatus.BatchOperationResult' description: | If only some or none of the entities have been successfully merged, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. @@ -1768,6 +1763,7 @@ paths: is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' /temporal/entities: @@ -2581,19 +2577,17 @@ paths: '400': $ref: '#/components/responses/BadRequest' '404': - allOf: - $ref: '#/components/responses/NotFound' description: | It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. + $ref: '#/components/responses/NotFound' '422': - allOf: - $ref: '#/components/responses/Unprocessable' description: | It is used when a client indicated an @context of type "Cached", see clause 6.3.2. + $ref: '#/components/responses/Unprocessable' delete: tags: - JSON-LD Context API @@ -2626,17 +2620,15 @@ paths: '400': $ref: '#/components/responses/BadRequest' '404': - allOf: - $ref: '#/components/responses/NotFound' description: | It is used when a client provided an @context identifier not known to the system, see clause 6.3.2. + $ref: '#/components/responses/NotFound' '503': - allOf: - $ref: '#/components/responses/ServiceUnavailable' description: | - It is used when re-downloading fails. + It is used when re-downloading fails. + $ref: '#/components/responses/ServiceUnavailable' components: headers: -- GitLab From 270693c8915dedbc4e7dea93cacf69bc42c6ddfe Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 26 May 2024 23:38:41 +0200 Subject: [PATCH 085/112] Updating example of custom OpenAPI schemas that are compliant with the NGSI-LD OAS for IoT sensors use case. --- .../iot-sensors-custom-schemas.yaml | 141 ++++++++++++++++++ .../customSchemas/sensor-custom-schemas.yaml | 39 ----- 2 files changed, 141 insertions(+), 39 deletions(-) create mode 100644 examples/customSchemas/iot-sensors-custom-schemas.yaml delete mode 100644 examples/customSchemas/sensor-custom-schemas.yaml diff --git a/examples/customSchemas/iot-sensors-custom-schemas.yaml b/examples/customSchemas/iot-sensors-custom-schemas.yaml new file mode 100644 index 0000000..9ca61c2 --- /dev/null +++ b/examples/customSchemas/iot-sensors-custom-schemas.yaml @@ -0,0 +1,141 @@ +openapi: 3.0.3 +info: + title: Example schemas for IoT device with temperature and humidity sensors + version: 0.0.1 + description: | + Example schemas compliant with the NGSI-LD OAS metamodel according to ETSI GS CIM 009. +paths: {} +components: + schemas: + TemperatureSensor: + description: | + NGSI-LD Entity Type that represents a temperature sensor. + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Entity' + - type: object + properties: + type: + description: NGSI-LD Entity identifier. It has to be TemperatureSensor. + type: string + enum: + - TemperatureSensor + default: TemperatureSensor + temperature: + $ref: '#/components/schemas/Temperature' + - required: + - type + - temperature + Temperature: + description: | + NGSI-LD Property Type. The temperature measurement. + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - type: object + properties: + value: + type: number + required: + - value + additionalProperties: false + HumiditySensor: + description: | + NGSI-LD Entity Type that represents a humidity sensor. + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Entity' + - type: object + properties: + type: + description: NGSI-LD Entity identifier. It has to be HumiditySensor. + type: string + enum: + - HumiditySensor + default: HumiditySensor + humidity: + $ref: '#/components/schemas/Humidity' + - required: + - type + - humidity + Humidity: + description: | + NGSI-LD Property Type. The humidity measurement. + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - type: object + properties: + value: + type: number + required: + - value + additionalProperties: false + IotDevice: + description: | + NGSI-LD Entity Type that represents an IoT device. + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Entity' + - type: object + properties: + type: + description: NGSI-LD Entity identifier. It has to be IotDevice. + type: string + enum: + - IotDevice + default: IotDevice + name: + $ref: '#/components/schemas/IotName' + description: + $ref: '#/components/schemas/IotDescription' + hasTemperatureSensor: + $ref: '#/components/schemas/HasTemperatureSensor' + hasHumiditySensor: + $ref: '#/components/schemas/HasHumiditySensor' + - required: + - type + - description + IotName: + description: NGSI-LD Property Type. The IoT device name. + additionalProperties: false + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - type: object + properties: + value: + type: string + required: + - value + IotDescription: + description: NGSI-LD Property Type. The IoT device description. + additionalProperties: false + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - type: object + properties: + value: + type: string + required: + - value + HasTemperatureSensor: + additionalProperties: false + description: | + NGSI-LD Relationship Type to identify a temperature sensor of the IoT device (i.e., the identifier of an NGSI-LD + Entity of type TemperatureSensor). + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Relationship' + - type: object + properties: + object: + type: string + required: + - object + HasHumiditySensor: + additionalProperties: false + description: | + NGSI-LD Relationship Type to identify a humidity sensor of the IoT device (i.e., the identifier of an NGSI-LD + Entity of type HumiditySensor). + allOf: + - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Relationship' + - type: object + properties: + object: + type: string + required: + - object \ No newline at end of file diff --git a/examples/customSchemas/sensor-custom-schemas.yaml b/examples/customSchemas/sensor-custom-schemas.yaml deleted file mode 100644 index f748552..0000000 --- a/examples/customSchemas/sensor-custom-schemas.yaml +++ /dev/null @@ -1,39 +0,0 @@ -openapi: 3.0.3 -info: - title: Example schemas for a temperature sensor - version: 0.0.1 - description: | - Example schemas compliant with the NGSI-LD OAS V1.6.1 metamodel according to ETSI GS CIM 009 V1.6.1. -paths: {} -components: - schemas: - TemperatureSensor: - description: | - NGSI-LD Entity Type that represents a temperature sensor. - allOf: - - $ref: 'https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml#/components/schemas/Entity' - - type: object - properties: - type: - description: NGSI-LD Entity identifier. It has to be TemperatureSensor. - type: string - enum: - - TemperatureSensor - default: TemperatureSensor - temperature: - $ref: '#/components/schemas/Temperature' - - required: - - type - - temperature - Temperature: - description: | - NGSI-LD Property Type. The temperature measurement. - allOf: - - $ref: 'https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml#/components/schemas/Property' - - type: object - properties: - value: - type: number - required: - - value - additionalProperties: false \ No newline at end of file -- GitLab From a5445472600bc52b23e99a1a1411280a56e03dbb Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 26 May 2024 23:41:29 +0200 Subject: [PATCH 086/112] Uploading @context vocabulary for NGSI-LD API v1.7.1. --- coreContext/ngsi-ld-core-context-v1.7.jsonld | 299 +++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 coreContext/ngsi-ld-core-context-v1.7.jsonld diff --git a/coreContext/ngsi-ld-core-context-v1.7.jsonld b/coreContext/ngsi-ld-core-context-v1.7.jsonld new file mode 100644 index 0000000..3f21a56 --- /dev/null +++ b/coreContext/ngsi-ld-core-context-v1.7.jsonld @@ -0,0 +1,299 @@ +{ + "@context": { + + "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", + "geojson": "https://purl.org/geojson/vocab#", + "id": "@id", + "type": "@type", + + "Attribute": "ngsi-ld:Attribute", + "AttributeList": "ngsi-ld:AttributeList", + "ContextSourceNotification": "ngsi-ld:ContextSourceNotification", + "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration", + "Date": "ngsi-ld:Date", + "DateTime": "ngsi-ld:DateTime", + "EntityType": "ngsi-ld:EntityType", + "EntityTypeInfo": "ngsi-ld:EntityTypeInfo", + "EntityTypeList": "ngsi-ld:EntityTypeList", + "Feature": "geojson:Feature", + "FeatureCollection": "geojson:FeatureCollection", + "GeoProperty": "ngsi-ld:GeoProperty", + "GeometryCollection": "geojson:GeometryCollection", + "LineString": "geojson:LineString", + "LanguageProperty": "ngsi-ld:LanguageProperty", + "MultiLineString": "geojson:MultiLineString", + "MultiPoint": "geojson:MultiPoint", + "MultiPolygon": "geojson:MultiPolygon", + "Notification": "ngsi-ld:Notification", + "Point": "geojson:Point", + "Polygon": "geojson:Polygon", + "Property": "ngsi-ld:Property", + "Relationship": "ngsi-ld:Relationship", + "Subscription": "ngsi-ld:Subscription", + "TemporalProperty": "ngsi-ld:TemporalProperty", + "Time": "ngsi-ld:Time", + + "accept": "ngsi-ld:accept", + "attributeCount": "attributeCount", + "attributeDetails": "attributeDetails", + "attributeList": { + "@id": "ngsi-ld:attributeList", + "@type": "@vocab" + }, + "attributeName": { + "@id": "ngsi-ld:attributeName", + "@type": "@vocab" + }, + "attributeNames": { + "@id": "ngsi-ld:attributeNames", + "@type": "@vocab" + }, + "attributeTypes": { + "@id": "ngsi-ld:attributeTypes", + "@type": "@vocab" + }, + "attributes": { + "@id": "ngsi-ld:attributes", + "@type": "@vocab" + }, + "attrs": "ngsi-ld:attrs", + "avg": { + "@id": "ngsi-ld:avg", + "@container": "@list" + }, + "bbox": { + "@container": "@list", + "@id": "geojson:bbox" + }, + "cacheDuration": "ngsi-ld:cacheDuration", + + "contextSourceInfo": "ngsi-ld:contextSourceInfo", + "cooldown": "ngsi-ld:cooldown", + "coordinates": { + "@container": "@list", + "@id": "geojson:coordinates" + }, + "createdAt": { + "@id": "ngsi-ld:createdAt", + "@type": "DateTime" + }, + "csf": "ngsi-ld:csf", + "data": "ngsi-ld:data", + "datasetId": { + "@id": "ngsi-ld:datasetId", + "@type": "@id" + }, + "deletedAt": { + "@id": "ngsi-ld:deletedAt", + "@type": "DateTime" + }, + "description": "http://purl.org/dc/terms/description", + "detail": "ngsi-ld:detail", + "distinctCount": { + "@id": "ngsi-ld:distinctCount", + "@container": "@list" + }, + "endAt": { + "@id": "ngsi-ld:endAt", + "@type": "DateTime" + }, + "endTimeAt": { + "@id": "ngsi-ld:endTimeAt", + "@type": "DateTime" + }, + "endpoint": "ngsi-ld:endpoint", + "entities": "ngsi-ld:entities", + "entityCount": "ngsi-ld:entityCount", + "entityId": { + "@id": "ngsi-ld:entityId", + "@type": "@id" + }, + "error": "ngsi-ld:error", + "errors": "ngsi-ld:errors", + "expiresAt": { + "@id": "ngsi-ld:expiresAt", + "@type": "DateTime" + }, + "features": { + "@container": "@set", + "@id": "geojson:features" + }, + "format": "ngsi-ld:format", + "geoQ": "ngsi-ld:geoQ", + "geometry": "geojson:geometry", + "geoproperty": "ngsi-ld:geoproperty", + "georel": "ngsi-ld:georel", + "idPattern": "ngsi-ld:idPattern", + "information": "ngsi-ld:information", + "instanceId": { + "@id": "ngsi-ld:instanceId", + "@type": "@id" + }, + "isActive": "ngsi-ld:isActive", + "key": "ngsi-ld:hasKey", + "lang": "ngsi-ld:lang", + "languageMap": { + "@id": "ngsi-ld:hasLanguageMap", + "@container": "@language" + }, + "languageMaps": { + "@id": "ngsi-ld:hasLanguageMaps", + "@container": "@list" + }, + "lastFailure": { + "@id": "ngsi-ld:lastFailure", + "@type": "DateTime" + }, + "lastNotification": { + "@id": "ngsi-ld:lastNotification", + "@type": "DateTime" + }, + "lastSuccess": { + "@id": "ngsi-ld:lastSuccess", + "@type": "DateTime" + }, + "localOnly": "ngsi-ld:localOnly", + "location": "ngsi-ld:location", + "management": "ngsi-ld:management", + "managementInterval": "ngsi-ld:managementInterval", + "max": { + "@id": "ngsi-ld:max", + "@container": "@list" + }, + "min": { + "@id": "ngsi-ld:min", + "@container": "@list" + }, + "mode": "ngsi-ld:mode", + "modifiedAt": { + "@id": "ngsi-ld:modifiedAt", + "@type": "DateTime" + }, + "notification": "ngsi-ld:notification", + "notificationTrigger": "ngsi-ld:notificationTrigger", + "notifiedAt": { + "@id": "ngsi-ld:notifiedAt", + "@type": "DateTime" + }, + "notifierInfo": "ngsi-ld:notifierInfo", + "notUpdated": "ngsi-ld:notUpdated", + "object": { + "@id": "ngsi-ld:hasObject", + "@type": "@id" + }, + "objects": { + "@id": "ngsi-ld:hasObjects", + "@container": "@list" + }, + "observationInterval": "ngsi-ld:observationInterval", + "observationSpace": "ngsi-ld:observationSpace", + "observedAt": { + "@id": "ngsi-ld:observedAt", + "@type": "DateTime" + }, + "operationSpace": "ngsi-ld:operationSpace", + "operations": "ngsi-ld:operations", + "previousLanguageMap": { + "@id": "ngsi-ld:hasPreviousLanguageMap", + "@container": "@language" + }, + "previousObject": { + "@id": "ngsi-ld:hasPreviousObject", + "@type": "@id" + }, + "previousValue": "ngsi-ld:hasPreviousValue", + "properties": "geojson:properties", + "propertyNames": { + "@id": "ngsi-ld:propertyNames", + "@type": "@vocab" + }, + "q": "ngsi-ld:q", + "reason": "ngsi-ld:reason", + "receiverInfo": "ngsi-ld:receiverInfo", + "refreshRate": "ngsi-ld:refreshRate", + "registrationId": "ngsi-ld:registrationId", + "registrationName": "ngsi-ld:registrationName", + "relationshipNames": { + "@id": "ngsi-ld:relationshipNames", + "@type": "@vocab" + }, + "scope": "ngsi-ld:scope", + "scopeQ": "ngsi-ld:scopeQ", + "showChanges": "ngsi-ld:showChanges", + "startAt": { + "@id": "ngsi-ld:startAt", + "@type": "DateTime" + }, + "status": "ngsi-ld:status", + "stddev": { + "@id": "ngsi-ld:stddev", + "@container": "@list" + }, + "subscriptionId": { + "@id": "ngsi-ld:subscriptionId", + "@type": "@id" + }, + "subscriptionName": "ngsi-ld:subscriptionName", + "success": { + "@id": "ngsi-ld:success", + "@type": "@id" + }, + "sum": { + "@id": "ngsi-ld:sum", + "@container": "@list" + }, + "sumsq": { + "@id": "ngsi-ld:sumsq", + "@container": "@list" + }, + "sysAttrs": "ngsi-ld:sysAttrs", + "temporalQ": "ngsi-ld:temporalQ", + "tenant": { + "@id": "ngsi-ld:tenant", + "@type": "@id" + }, + "throttling": "ngsi-ld:throttling", + "timeAt": { + "@id": "ngsi-ld:timeAt", + "@type": "DateTime" + }, + "timeInterval": "ngsi-ld:timeInterval", + "timeout": "ngsi-ld:timeout", + "timeproperty": "ngsi-ld:timeproperty", + "timerel": "ngsi-ld:timerel", + "timesFailed": "ngsi-ld:timesFailed", + "timesSent": "ngsi-ld:timesSent", + "title": "http://purl.org/dc/terms/title", + "totalCount": { + "@id": "ngsi-ld:totalCount", + "@container": "@list" + }, + "triggerReason": "ngsi-ld:triggerReason", + "typeList": { + "@id": "ngsi-ld:typeList", + "@type": "@vocab" + }, + "typeName": { + "@id": "ngsi-ld:typeName", + "@type": "@vocab" + }, + "typeNames": { + "@id": "ngsi-ld:typeNames", + "@type": "@vocab" + }, + "unchanged": "ngsi-ld:unchanged", + "unitCode": "ngsi-ld:unitCode", + "updated": "ngsi-ld:updated", + "uri": "ngsi-ld:uri", + "value": "ngsi-ld:hasValue", + "values": { + "@id": "ngsi-ld:hasValues", + "@container": "@list" + }, + "watchedAttributes": { + "@id": "ngsi-ld:watchedAttributes", + "@type": "@vocab" + }, + "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/" + } +} -- GitLab From 0dc2369582289ed1250745268f60f1f3930447e0 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 26 May 2024 23:47:58 +0200 Subject: [PATCH 087/112] Updating info and externalDocs sections of the NGSI-LD OAS to indicate the version 1.7.1 of NGSI-LD API. --- ngsi-ld-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 81d96ea..5f4d77c 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: title: NGSI-LD OAS - version: 1.6.1 + version: 1.7.1 description: OpenAPI Specification for NGSI-LD API. contact: url: https://www.etsi.org/committee/cim @@ -10,8 +10,8 @@ info: url: https://forge.etsi.org/legal-matters externalDocs: - description: ETSI GS CIM 009 V1.6.1 cross-cutting Context Information Management (CIM); NGSI-LD API - url: https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.06.01_60/gs_CIM009v010601p.pdf + description: ETSI GS CIM 009 V1.7.1 cross-cutting Context Information Management (CIM); NGSI-LD API + url: https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.07.01_60/gs_CIM009v010701p.pdf servers: - url: '{protocol}://{hostname}:{port}/ngsi-ld/v1' -- GitLab From 5bb0413e51f8c2d1fffc6750e2bfa69c89608a3d Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 27 May 2024 00:02:23 +0200 Subject: [PATCH 088/112] Adding the count query parameter and NGSILD-Results-Count HTTP header for 200 response within GET /temporal/entities operation as stated by clause 6.3.13 Counting Number of Results in ETSI GS CIM 009 V1.7.1. --- ngsi-ld-api.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5f4d77c..c4a4d0b 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1844,6 +1844,7 @@ paths: - $ref: '#/components/parameters/Query.aggrPeriodDuration' - $ref: '#/components/parameters/Query.scopeQ' - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' - $ref: '#/components/parameters/Query.options.temporal' - $ref: '#/components/parameters/Query.options.sysAttrs' # Local Query param @@ -1858,6 +1859,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' content: application/json: schema: -- GitLab From c674f779aa9ab1fbb6c75465137585ade87640b5 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 27 May 2024 00:25:22 +0200 Subject: [PATCH 089/112] Adding a new schema named VocabularyProperty for the new data type considered in the clause 5.2.35 VocabularyProperty of ETSI GS CIM 009 V1.7.1. --- ngsi-ld-api.yaml | 67 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index c4a4d0b..59c647e 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3888,6 +3888,10 @@ components: - type: array items: $ref: '#/components/schemas/LanguageProperty' + - $ref: '#/components/schemas/VocabularyProperty' + - type: array + items: + $ref: '#/components/schemas/VocabularyProperty' EntityInfo: description: | 5.2.8 This type represents what Entities, Entity Types or group of Entity ids @@ -3996,6 +4000,9 @@ components: - type: array items: $ref: '#/components/schemas/LanguageProperty' + - type: array + items: + $ref: '#/components/schemas/VocabularyProperty' EntityType: description: | 5.2.25 This type represents the data needed to define the elements of the detailed @@ -5158,6 +5165,66 @@ components: required: - updated - notUpdated + VocabularyProperty: + description: | + 5.2.35 NGSI-LD VocabularyProperty. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - VocabularyProperty + default: VocabularyProperty + vocab: + description: | + String Values which shall be type coerced to URIs based on the supplied @context. + oneOf: + - type: string + - type: array + items: + type: string + previousVocab: + description: | + Previous Vocabulary Property vocab. Only used in notifications, if the showChanges + option is explicitly requested. + oneOf: + - type: string + - type: array + items: + type: string + readOnly: true + observedAt: + description: | + Timestamp. See clause 4.8. + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated temporal attributes. + systemGeneratedAttrs: + allOf: + - $ref: '#/components/schemas/SystemGeneratedAttributes' + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' responses: BadRequest: -- GitLab From d33134d069bde559b02557f37a857f110caeae61 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 27 May 2024 00:32:31 +0200 Subject: [PATCH 090/112] Adding the previousValue parameter in GeoProperty schemas as stated by clause 5.2.7 GeoProperty of ETSI GS CIM 009 V1.7.1. --- ngsi-ld-api.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 59c647e..ab14292 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -4336,6 +4336,12 @@ components: type: string format: uri readOnly: true + previousValue: + description: | + Previous GeoProperty value. Only used in notifications, if the showChanges + option is explicitly requested. + $ref: '#/components/schemas/Geometry' + readOnly: true additionalProperties: oneOf: - $ref: '#/components/schemas/Property' -- GitLab From f02ab2e2f1ed1acc18bfee8b317d148d948897bc Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 27 May 2024 00:38:42 +0200 Subject: [PATCH 091/112] Adding the jsonldContext parameter in Subscription.Common schema as stated by clause 5.2.12 Subscription of ETSI GS CIM 009 V1.7.1. --- ngsi-ld-api.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index ab14292..9e03d26 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -5067,6 +5067,13 @@ components: - paused - expired readOnly: true + jsonldContext: + description: | + The dereferenceable URI of the JSON-LD @context to be used when sending + a notification resulting from the subscription. If not provided, the + @context used for the subscription shall be used as a default. + type: string + format: uri Subscription.Periodic: allOf: - $ref: '#/components/schemas/Subscription.Common' -- GitLab From a0b134f5e0925cf7cfd3b4269bc42ad21d77f699 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 27 May 2024 01:02:56 +0200 Subject: [PATCH 092/112] Adding the HTTP 501 NotImplemented response as stated by clause 6.3.7 Representation of Entities of ETSI GS CIM 009 V1.7.1. Including the NotImplemente response for the following operations: GET /entities and GET /entities/{entityId}. --- ngsi-ld-api.yaml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 9e03d26..8bf99c3 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -172,6 +172,13 @@ paths: NGSILD-Warning: $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' + '501': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/NotImplemented' /entities/{entityId}: get: @@ -246,6 +253,13 @@ paths: NGSILD-Warning: $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' + '501': + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + $ref: '#/components/responses/NotImplemented' delete: tags: - Context Information Provision @@ -5347,6 +5361,23 @@ components: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/json+ld: + schema: + $ref: '#/components/schemas/ProblemDetails' + application/geo: + schema: + $ref: '#/components/schemas/ProblemDetails' + NotImplemented: + description: | + It is used by Registered Context Sources to indicate that the data format + of the request is unsupported see clause 6.3.7. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' content: application/json: schema: -- GitLab From 23ab29b46712283eff96ff707c6d50d6a405453d Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Mon, 27 May 2024 10:58:09 +0200 Subject: [PATCH 093/112] Adding the optional query parameter type for the selection of Entity type in additional operations as indicated in ETSI GS CIM 009 V1.7.1 (i.e., 6.5.3.1 GET /entities/{entityId}, 6.5.3.2 DELETE /entities/{entityId}, 6.5.3.3 PUT /entities/{entityId}, 6.5.3.4 PATCH /entities/{entityId}, 6.6.3.1 POST /entities/{entityId}/attrs/, 6.6.3.2 PATCH /entities/{entityId}/attrs/, 6.7.3.1 PATCH /entities/{entityId}/attrs/{attrId}, 6.7.3.2 DELETE /entities/{entityId}/attrs/{attrId}, and 6.7.3.3 PUT /entities/{entityId}/attrs/{attrId}). Adding the optional query parameter options for the selection of noOverwrite value for 6.6.3.1 POST /entities/{entityId}/attrs/ operation as indicated in ETSI GS CIM 009 V1.7.1. --- ngsi-ld-api.yaml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 8bf99c3..e5d68d5 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -195,6 +195,7 @@ paths: # Path params - $ref: '#/components/parameters/Path.entityId' # Query params + - $ref: '#/components/parameters/Query.type' - $ref: '#/components/parameters/Query.attrs' - $ref: '#/components/parameters/Query.geometryProperty' - $ref: '#/components/parameters/Query.lang' @@ -273,6 +274,8 @@ paths: parameters: # Path params - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.type' # Local Query param - $ref: '#/components/parameters/Query.local' # Request headers @@ -325,6 +328,7 @@ paths: items: $ref: '#/components/schemas/options.representation' required: false + - $ref: '#/components/parameters/Query.type' - $ref: '#/components/parameters/Query.observedAt' - $ref: '#/components/parameters/Query.lang' # Local Query param @@ -376,6 +380,8 @@ paths: parameters: # Path params - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.type' # Local Query param - $ref: '#/components/parameters/Query.local' # Request headers @@ -428,6 +434,7 @@ paths: # Path params - $ref: '#/components/parameters/Path.entityId' # Query params + - $ref: '#/components/parameters/Query.type' - $ref: '#/components/parameters/Query.options.noOverwrite' # Local Query param - $ref: '#/components/parameters/Query.local' @@ -481,6 +488,7 @@ paths: - $ref: '#/components/parameters/Path.entityId' # Local Query param - $ref: '#/components/parameters/Query.local' + - $ref: '#/components/parameters/Query.type' # Request headers - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' @@ -533,6 +541,7 @@ paths: - $ref: '#/components/parameters/Path.attrId' # Local Query param - $ref: '#/components/parameters/Query.local' + - $ref: '#/components/parameters/Query.type' # Request headers - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' @@ -570,6 +579,7 @@ paths: # Query params - $ref: '#/components/parameters/Query.deleteAll' - $ref: '#/components/parameters/Query.datasetId' + - $ref: '#/components/parameters/Query.type' # Local Query param - $ref: '#/components/parameters/Query.local' # Request headers @@ -605,6 +615,7 @@ paths: - $ref: '#/components/parameters/Path.attrId' # Local Query param - $ref: '#/components/parameters/Query.local' + - $ref: '#/components/parameters/Query.type' # Request headers - $ref: '#/components/parameters/Headers.Link' - $ref: '#/components/parameters/Headers.ngsildTenant' @@ -3305,7 +3316,7 @@ components: # options.noOverwrite: description: | - 6.16.3 For POST method associated to the operation "Batch Entity Update", the "noOvevwrite" + 6.16.3 For POST method associated to the operations "Batch Entity Update" and "Append Entity Attributes", the "noOvevwrite" options query parameter indicates that no attribute overwrite shall be performed. type: string enum: -- GitLab From 84f61ff4f54ef82c3101cbefe43c3d938d4c2d28 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 11:28:11 +0200 Subject: [PATCH 094/112] Fixing issues with headers definition within the operation responses on NGSI-LD OAS. Including all the possible headers within the global response defined on responses section of NGSI-LD OAS. --- ngsi-ld-api.yaml | 47 ++++++++--------------------------------------- 1 file changed, 8 insertions(+), 39 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index e5d68d5..aa114eb 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -78,11 +78,6 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': - headers: - Location: - $ref: '#/components/headers/Location' - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': $ref: '#/components/responses/BadRequest' @@ -166,18 +161,8 @@ paths: schema: $ref: '#/components/schemas/FeatureCollection' '400': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '501': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotImplemented' /entities/{entityId}: @@ -241,25 +226,10 @@ paths: schema: $ref: '#/components/schemas/Feature' '400': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/BadRequest' '404': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotFound' '501': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' - NGSILD-Warning: - $ref: '#/components/headers/NGSILD-Warning' $ref: '#/components/responses/NotImplemented' delete: tags: @@ -289,19 +259,10 @@ paths: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' '207': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' $ref: '#/components/responses/MultiStatus.BatchOperationResult' '400': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' $ref: '#/components/responses/BadRequest' '404': - headers: - NGSILD-Tenant: - $ref: '#/components/headers/NGSILD-Tenant' $ref: '#/components/responses/NotFound' patch: tags: @@ -5273,6 +5234,8 @@ components: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -5306,6 +5269,8 @@ components: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' content: application/json: schema: @@ -5338,6 +5303,8 @@ components: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -5389,6 +5356,8 @@ components: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: -- GitLab From 6a110c1a651397827427fd1e72100895d41dd4ca Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 12:40:28 +0200 Subject: [PATCH 095/112] For schemas definitions with to other schemas that include additional sibling descriptions, wrapping the into allOf. --- ngsi-ld-api.yaml | 99 +++++++++++++++++++++++++++++++----------------- 1 file changed, 65 insertions(+), 34 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index aa114eb..2b6eba6 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3187,10 +3187,11 @@ components: content: application/json: schema: - $ref: '#/components/schemas/EntityTemporal' - required: - - id - - type + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type application/json+ld: schema: allOf: @@ -3492,7 +3493,8 @@ components: error: description: | One instance per Entity in error. - $ref: '#/components/schemas/ProblemDetails' + allOf: + - $ref: '#/components/schemas/ProblemDetails' required: - entityId - error @@ -3630,7 +3632,8 @@ components: Entity information as specified by the observedAt Temporal Property. A temporal query based on the observedAt Temporal Property, which is the default, is matched against the observationInterval for overlap. - $ref: '#/components/schemas/TimeInterval' + allOf: + - $ref: '#/components/schemas/TimeInterval' managementInterval: description: | If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity @@ -3639,23 +3642,27 @@ components: information as specified by the createdAt, modifiedAt and deletedAt Temporal Properties. A temporal query based on the createdAt, modifiedAt or deletedAt Temporal Property is matched against the managementInterval for overlap. - $ref: '#/components/schemas/TimeInterval' + allOf: + - $ref: '#/components/schemas/TimeInterval' location: description: | Location for which the Context Source may be able to provide information. - $ref: '#/components/schemas/Geometry' + allOf: + - $ref: '#/components/schemas/Geometry' observationSpace: description: | Geographic location that includes the observation spaces of all entities as specified by their respective observationSpace GeoProperty for which the Context Source may be able to provide information. - $ref: '#/components/schemas/Geometry' + allOf: + - $ref: '#/components/schemas/Geometry' operationSpace: description: | Geographic location that includes the operation spaces of all entities as specified by their respective operationSpace GeoProperty for which the Context Source may be able to provide information. - $ref: '#/components/schemas/Geometry' + allOf: + - $ref: '#/components/schemas/Geometry' expiresAt: description: | Provides an expiration date. When passed the Context Source Registration @@ -3710,7 +3717,8 @@ components: description: | Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. - $ref: '#/components/schemas/RegistrationManagementInfo' + allOf: + - $ref: '#/components/schemas/RegistrationManagementInfo' # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: allOf: @@ -3843,15 +3851,18 @@ components: location: description: | Default geospatial Property of an entity. See clause 4.7. - $ref: '#/components/schemas/GeoProperty' + allOf: + - $ref: '#/components/schemas/GeoProperty' observationSpace: description: | See clause 4.7. - $ref: '#/components/schemas/GeoProperty' + allOf: + - $ref: '#/components/schemas/GeoProperty' operationSpace: description: | See clause 4.7. - $ref: '#/components/schemas/GeoProperty' + allOf: + - $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: allOf: @@ -3959,15 +3970,18 @@ components: location: description: | Default geospatial Property of an entity. See clause 4.7. - $ref: '#/components/schemas/GeoProperty' + allOf: + - $ref: '#/components/schemas/GeoProperty' observationSpace: description: | See clause 4.7. - $ref: '#/components/schemas/GeoProperty' + allOf: + - $ref: '#/components/schemas/GeoProperty' operationSpace: description: | See clause 4.7. - $ref: '#/components/schemas/GeoProperty' + allOf: + - $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: allOf: @@ -4104,16 +4118,19 @@ components: geometry: description: | Null if no matching GeoProperty. - $ref: '#/components/schemas/Geometry' + allOf: + - $ref: '#/components/schemas/Geometry' properties: description: | List of attributes as mandated by clause 5.2.31. - $ref: '#/components/schemas/FeatureProperties' + allOf: + - $ref: '#/components/schemas/FeatureProperties' '@context': description: | JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240). - $ref: '#/components/schemas/LdContext' + allOf: + - $ref: '#/components/schemas/LdContext' required: - id - type @@ -4141,7 +4158,8 @@ components: description: | JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240). - $ref: '#/components/schemas/LdContext' + allOf: + - $ref: '#/components/schemas/LdContext' required: - type FeatureProperties: @@ -4301,11 +4319,13 @@ components: value: description: | Geolocation encoded as GeoJSON. As mandated by clause 4.7. - $ref: '#/components/schemas/Geometry' + allOf: + - $ref: '#/components/schemas/Geometry' observedAt: description: | Timestamp. See clause 4.8. - $ref: '#/components/schemas/ObservedAt' + allOf: + - $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. @@ -4326,7 +4346,8 @@ components: description: | Previous GeoProperty value. Only used in notifications, if the showChanges option is explicitly requested. - $ref: '#/components/schemas/Geometry' + allOf: + - $ref: '#/components/schemas/Geometry' readOnly: true additionalProperties: oneOf: @@ -4406,7 +4427,8 @@ components: observedAt: description: | Timestamp. See clause 4.8. - $ref: '#/components/schemas/ObservedAt' + allOf: + - $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. @@ -4602,7 +4624,8 @@ components: endpoint: description: | Notification endpoint details. - $ref: '#/components/schemas/Endpoint' + allOf: + - $ref: '#/components/schemas/Endpoint' status: description: | Status of the Notification. It shall be "ok" if the last attempt to notify the subscriber succeeded. @@ -4731,7 +4754,8 @@ components: observedAt: description: | Timestamp. See clause 4.8. - $ref: '#/components/schemas/ObservedAt' + allOf: + - $ref: '#/components/schemas/ObservedAt' unitCode: description: | Property Value's unit code. @@ -4805,7 +4829,8 @@ components: geoQ: description: | Geoquery that shall be matched by Entities in order be retrieved. - $ref: '#/components/schemas/GeoQuery' + allOf: + - $ref: '#/components/schemas/GeoQuery' csf: description: | Context source filter that shall be matched by Context Source Registrations describing @@ -4834,7 +4859,8 @@ components: temporalQ: description: | Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). - $ref: '#/components/schemas/TemporalQuery' + allOf: + - $ref: '#/components/schemas/TemporalQuery' - required: - temporalQ RegistrationInfo: @@ -4914,7 +4940,8 @@ components: observedAt: description: | Timestamp. See clause 4.8. - $ref: '#/components/schemas/ObservedAt' + allOf: + - $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of target relationship objects. @@ -5005,7 +5032,8 @@ components: geoQ: description: | Geoquery that shall be met by subscribed entities in order to trigger the notification. - $ref: '#/components/schemas/GeoQuery' + allOf: + - $ref: '#/components/schemas/GeoQuery' csf: description: | Context source filter that shall be met by Context Source Registrations describing Context Sources @@ -5021,7 +5049,8 @@ components: notification: description: | Notification details. - $ref: '#/components/schemas/NotificationParams' + allOf: + - $ref: '#/components/schemas/NotificationParams' expiresAt: description: | Expiration date for the subscription. @@ -5031,7 +5060,8 @@ components: description: | Temporal Query to be used only in Context Registration Subscriptions for matching Context Source Registrations of Context Sources providing temporal information. - $ref: '#/components/schemas/TemporalQuery' + allOf: + - $ref: '#/components/schemas/TemporalQuery' scopeQ: description: | Scope query. @@ -5197,7 +5227,8 @@ components: observedAt: description: | Timestamp. See clause 4.8. - $ref: '#/components/schemas/ObservedAt' + allOf: + - $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. -- GitLab From 5396ebf3b21e8ac265c9473af9fed1dec5692733 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 12:52:16 +0200 Subject: [PATCH 096/112] Deleting additionalProperties statement from Geometry.position schema definition. --- ngsi-ld-api.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2b6eba6..24132da 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -4208,7 +4208,6 @@ components: maxItems: 3 items: type: number - additionalProperties: false Geometry.positionArray: description: | An array of positions. -- GitLab From 2ad4e8b2d9e6d087562404f8a23f8fb4a9278c9d Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 19:46:54 +0200 Subject: [PATCH 097/112] Updating README file. --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 19b5df0..8803e49 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,9 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API spe ### Navigate API -* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) -* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) -* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/-/raw/1.6.1/ngsi-ld-api.yaml) +* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) +* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) +* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) ## Developers @@ -29,7 +29,8 @@ The NGSI-LD API specification has been developed using VS Code supported by the The repository includes the following resources that may be useful when using the NGSI-LD API: - [Core JSON-LD @context](./coreContext/): This folder contains JSON-LD core @context defined by the NGSI-LD API. For convencience, the folder includes @context files for different versions of the API. - [NGSI-LD payload examples](./examples/): Includes examples of NGSI-LD payloads for multiple types of NGSI-LD operations. These examples can also be found in the Annex sections of the ETSI ISG CIM 009 document. - +- [OpenAPI schemas compliant with NGSI-LD OAS](./examples/customSchemas/): Includes examples to show how to define custom OpenAPI schemas that are compatible with the NGSI-LD OAS. It allows developers to define specific-purpose applications where they model their own OpenAPI schemas, so they are compatible with the NGSI-LD meta-model defined within the NGSI-LD OAS. +- ## License The content of this repository and the files contained are released under the BSD-3-Clause license. See the attached LICENSE file or visit https://forge.etsi.org/legal-matters. -- GitLab From 8dfdd0555bbcb8d1538aa116dad45a4001eda6ae Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 19:55:01 +0200 Subject: [PATCH 098/112] Deleting original LICENSE. --- LICENSE | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 LICENSE diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 4436d6d..0000000 --- a/LICENSE +++ /dev/null @@ -1,23 +0,0 @@ -Copyright 2019 ETSI - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: -1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. -3. Neither the name of the copyright holder nor the names of its contributors - may be used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. -IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, -INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE -OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -OF THE POSSIBILITY OF SUCH DAMAGE. \ No newline at end of file -- GitLab From dcfdf9a3c662955f98290b4bc3bc2140f79f3ff1 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 20:01:05 +0200 Subject: [PATCH 099/112] Updating README file. --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 8803e49..d275a67 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,6 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API specified by the cross-cutting Context Information Management (CIM) ETSI Industry Specification Group (ISG). -> **IMPORTANT NOTE:** -> -> This is a fork of the original OpenAPI Specification for the NGSI-LD API, which is available on the ETSI Forge [here](https://forge.etsi.org/rep/cim/NGSI-LD). - ## Online Documentation ### Specification Document -- GitLab From beab36fa82feb55c9ff93cd410b77b685f6760b3 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 12 Jun 2024 20:02:39 +0200 Subject: [PATCH 100/112] Updating README file. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d275a67..3a342b1 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The repository includes the following resources that may be useful when using th - [Core JSON-LD @context](./coreContext/): This folder contains JSON-LD core @context defined by the NGSI-LD API. For convencience, the folder includes @context files for different versions of the API. - [NGSI-LD payload examples](./examples/): Includes examples of NGSI-LD payloads for multiple types of NGSI-LD operations. These examples can also be found in the Annex sections of the ETSI ISG CIM 009 document. - [OpenAPI schemas compliant with NGSI-LD OAS](./examples/customSchemas/): Includes examples to show how to define custom OpenAPI schemas that are compatible with the NGSI-LD OAS. It allows developers to define specific-purpose applications where they model their own OpenAPI schemas, so they are compatible with the NGSI-LD meta-model defined within the NGSI-LD OAS. -- + ## License The content of this repository and the files contained are released under the BSD-3-Clause license. See the attached LICENSE file or visit https://forge.etsi.org/legal-matters. -- GitLab From 580957ea0d7e0eb234d8d1a9c9418822bb887cc4 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 14 Jul 2024 01:46:58 +0200 Subject: [PATCH 101/112] Removing the allOf wrapper for schemas definition when they reference to other schemas that include additional sibling descriptions, because the original schema (i.e., the reference one) is lost. --- ngsi-ld-api.yaml | 132 ++++++++++++++++------------------------------- 1 file changed, 45 insertions(+), 87 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 24132da..4623e76 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3187,11 +3187,10 @@ components: content: application/json: schema: - allOf: - - $ref: '#/components/schemas/EntityTemporal' - - required: - - id - - type + $ref: '#/components/schemas/EntityTemporal' + required: + - id + - type application/json+ld: schema: allOf: @@ -3360,16 +3359,13 @@ components: type: object properties: createdAt: - allOf: - - $ref: '#/components/schemas/CreatedAt' + $ref: '#/components/schemas/CreatedAt' readOnly: true modifiedAt: - allOf: - - $ref: '#/components/schemas/ModifiedAt' + $ref: '#/components/schemas/ModifiedAt' readOnly: true deletedAt: - allOf: - - $ref: '#/components/schemas/DeletedAt' + $ref: '#/components/schemas/DeletedAt' readOnly: true CreatedAt: description: | @@ -3493,8 +3489,7 @@ components: error: description: | One instance per Entity in error. - allOf: - - $ref: '#/components/schemas/ProblemDetails' + $ref: '#/components/schemas/ProblemDetails' required: - entityId - error @@ -3632,8 +3627,7 @@ components: Entity information as specified by the observedAt Temporal Property. A temporal query based on the observedAt Temporal Property, which is the default, is matched against the observationInterval for overlap. - allOf: - - $ref: '#/components/schemas/TimeInterval' + $ref: '#/components/schemas/TimeInterval' managementInterval: description: | If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity @@ -3642,27 +3636,23 @@ components: information as specified by the createdAt, modifiedAt and deletedAt Temporal Properties. A temporal query based on the createdAt, modifiedAt or deletedAt Temporal Property is matched against the managementInterval for overlap. - allOf: - - $ref: '#/components/schemas/TimeInterval' + $ref: '#/components/schemas/TimeInterval' location: description: | Location for which the Context Source may be able to provide information. - allOf: - - $ref: '#/components/schemas/Geometry' + $ref: '#/components/schemas/Geometry' observationSpace: description: | Geographic location that includes the observation spaces of all entities as specified by their respective observationSpace GeoProperty for which the Context Source may be able to provide information. - allOf: - - $ref: '#/components/schemas/Geometry' + $ref: '#/components/schemas/Geometry' operationSpace: description: | Geographic location that includes the operation spaces of all entities as specified by their respective operationSpace GeoProperty for which the Context Source may be able to provide information. - allOf: - - $ref: '#/components/schemas/Geometry' + $ref: '#/components/schemas/Geometry' expiresAt: description: | Provides an expiration date. When passed the Context Source Registration @@ -3717,12 +3707,10 @@ components: description: | Holds additional optional registration management information that can be used to limit unnecessary distributed operation requests. - allOf: - - $ref: '#/components/schemas/RegistrationManagementInfo' + $ref: '#/components/schemas/RegistrationManagementInfo' # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' status: description: | Read-only. Status of the Registration. It shall be "ok" if the last attempt to perform a distributed @@ -3851,22 +3839,18 @@ components: location: description: | Default geospatial Property of an entity. See clause 4.7. - allOf: - - $ref: '#/components/schemas/GeoProperty' + $ref: '#/components/schemas/GeoProperty' observationSpace: description: | See clause 4.7. - allOf: - - $ref: '#/components/schemas/GeoProperty' + $ref: '#/components/schemas/GeoProperty' operationSpace: description: | See clause 4.7. - allOf: - - $ref: '#/components/schemas/GeoProperty' + $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' additionalProperties: oneOf: - $ref: '#/components/schemas/Property' @@ -3970,22 +3954,18 @@ components: location: description: | Default geospatial Property of an entity. See clause 4.7. - allOf: - - $ref: '#/components/schemas/GeoProperty' + $ref: '#/components/schemas/GeoProperty' observationSpace: description: | See clause 4.7. - allOf: - - $ref: '#/components/schemas/GeoProperty' + $ref: '#/components/schemas/GeoProperty' operationSpace: description: | See clause 4.7. - allOf: - - $ref: '#/components/schemas/GeoProperty' + $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' additionalProperties: oneOf: - type: array @@ -4118,19 +4098,16 @@ components: geometry: description: | Null if no matching GeoProperty. - allOf: - - $ref: '#/components/schemas/Geometry' + $ref: '#/components/schemas/Geometry' properties: description: | List of attributes as mandated by clause 5.2.31. - allOf: - - $ref: '#/components/schemas/FeatureProperties' + $ref: '#/components/schemas/FeatureProperties' '@context': description: | JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240). - allOf: - - $ref: '#/components/schemas/LdContext' + $ref: '#/components/schemas/LdContext' required: - id - type @@ -4158,8 +4135,7 @@ components: description: | JSON-LD @context. This field is only present if requested in the payload by the HTTP Prefer Header (IETF RFC 7240). - allOf: - - $ref: '#/components/schemas/LdContext' + $ref: '#/components/schemas/LdContext' required: - type FeatureProperties: @@ -4323,8 +4299,7 @@ components: observedAt: description: | Timestamp. See clause 4.8. - allOf: - - $ref: '#/components/schemas/ObservedAt' + $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. @@ -4332,8 +4307,7 @@ components: format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, @@ -4345,8 +4319,7 @@ components: description: | Previous GeoProperty value. Only used in notifications, if the showChanges option is explicitly requested. - allOf: - - $ref: '#/components/schemas/Geometry' + $ref: '#/components/schemas/Geometry' readOnly: true additionalProperties: oneOf: @@ -4426,8 +4399,7 @@ components: observedAt: description: | Timestamp. See clause 4.8. - allOf: - - $ref: '#/components/schemas/ObservedAt' + $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. @@ -4435,8 +4407,7 @@ components: format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, @@ -4623,8 +4594,7 @@ components: endpoint: description: | Notification endpoint details. - allOf: - - $ref: '#/components/schemas/Endpoint' + $ref: '#/components/schemas/Endpoint' status: description: | Status of the Notification. It shall be "ok" if the last attempt to notify the subscriber succeeded. @@ -4753,8 +4723,7 @@ components: observedAt: description: | Timestamp. See clause 4.8. - allOf: - - $ref: '#/components/schemas/ObservedAt' + $ref: '#/components/schemas/ObservedAt' unitCode: description: | Property Value's unit code. @@ -4766,8 +4735,7 @@ components: format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, @@ -4828,8 +4796,7 @@ components: geoQ: description: | Geoquery that shall be matched by Entities in order be retrieved. - allOf: - - $ref: '#/components/schemas/GeoQuery' + $ref: '#/components/schemas/GeoQuery' csf: description: | Context source filter that shall be matched by Context Source Registrations describing @@ -4858,8 +4825,7 @@ components: temporalQ: description: | Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). - allOf: - - $ref: '#/components/schemas/TemporalQuery' + $ref: '#/components/schemas/TemporalQuery' - required: - temporalQ RegistrationInfo: @@ -4939,8 +4905,7 @@ components: observedAt: description: | Timestamp. See clause 4.8. - allOf: - - $ref: '#/components/schemas/ObservedAt' + $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of target relationship objects. @@ -4948,8 +4913,7 @@ components: format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Relationship instance @@ -5031,8 +4995,7 @@ components: geoQ: description: | Geoquery that shall be met by subscribed entities in order to trigger the notification. - allOf: - - $ref: '#/components/schemas/GeoQuery' + $ref: '#/components/schemas/GeoQuery' csf: description: | Context source filter that shall be met by Context Source Registrations describing Context Sources @@ -5048,8 +5011,7 @@ components: notification: description: | Notification details. - allOf: - - $ref: '#/components/schemas/NotificationParams' + $ref: '#/components/schemas/NotificationParams' expiresAt: description: | Expiration date for the subscription. @@ -5059,8 +5021,7 @@ components: description: | Temporal Query to be used only in Context Registration Subscriptions for matching Context Source Registrations of Context Sources providing temporal information. - allOf: - - $ref: '#/components/schemas/TemporalQuery' + $ref: '#/components/schemas/TemporalQuery' scopeQ: description: | Scope query. @@ -5071,8 +5032,7 @@ components: type: string # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' status: description: | Read-only. Provided by the system when querying the details of a subscription. @@ -5226,8 +5186,7 @@ components: observedAt: description: | Timestamp. See clause 4.8. - allOf: - - $ref: '#/components/schemas/ObservedAt' + $ref: '#/components/schemas/ObservedAt' datasetId: description: | It allows identifying a set or group of property values. @@ -5235,8 +5194,7 @@ components: format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. systemGeneratedAttrs: - allOf: - - $ref: '#/components/schemas/SystemGeneratedAttributes' + $ref: '#/components/schemas/SystemGeneratedAttributes' instanceId: description: | A URI uniquely identifying a Property instance, -- GitLab From 8d23f4fa32ce7d7b2990eaf3b1be006b0eb6937a Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 14 Jul 2024 01:48:35 +0200 Subject: [PATCH 102/112] Deleting the required statements for timerel and timeAt query parameters of 5.7.4 Query Temporal Evolution of Entities, and indicating within the description of the operation that requirements. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 4623e76..2a5a214 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -1805,6 +1805,8 @@ paths: This operation allows querying the temporal evolution of Entities present in an NGSI-LD system. It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query. + + *The query parameters timerel and timeAt are required. operationId: queryTemporal parameters: # Query params @@ -1820,9 +1822,7 @@ paths: - $ref: '#/components/parameters/Query.geoproperty' - $ref: '#/components/parameters/Query.timeproperty' - $ref: '#/components/parameters/Query.timerel' - required: true - $ref: '#/components/parameters/Query.timeAt' - required: true - $ref: '#/components/parameters/Query.endTimeAt' - $ref: '#/components/parameters/Query.lastN' - $ref: '#/components/parameters/Query.lang' -- GitLab From 99cb67086e6929a5aae177f1c5d91035a2df454f Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 14 Jul 2024 02:01:10 +0200 Subject: [PATCH 103/112] Including NGSILD-Warning Header for all GET operations and for all type of HTTP responses, also for HTTP 20X responses. Adding NGSILD-Warning for the global responses of NGSI-LD OAS BadRequest, NotFound, NotImplemented, and Unprocessable. --- ngsi-ld-api.yaml | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2a5a214..3ba565c 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -711,6 +711,8 @@ paths: headers: NGSILD-Results-Count: $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -766,6 +768,9 @@ paths: '200': description: | A response body containing the JSON-LD representation of the target subscription. + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -934,6 +939,8 @@ paths: $ref: '#/components/headers/NGSILD-Tenant' NGSILD-Results-Count: $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -990,6 +997,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1143,6 +1152,8 @@ paths: $ref: '#/components/headers/NGSILD-Tenant' NGSILD-Results-Count: $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1200,6 +1211,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1650,6 +1663,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1847,6 +1862,8 @@ paths: $ref: '#/components/headers/NGSILD-Tenant' NGSILD-Results-Count: $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -1912,6 +1929,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2136,6 +2155,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2207,6 +2228,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2270,6 +2293,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2333,6 +2358,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2395,6 +2422,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2493,6 +2522,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -2546,6 +2577,8 @@ paths: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: @@ -5327,6 +5360,8 @@ components: headers: NGSILD-Tenant: $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' content: application/json: schema: -- GitLab From a8dabe4242de7faa9435ae0b8347e93cb7703b85 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 14 Jul 2024 02:04:31 +0200 Subject: [PATCH 104/112] Removing the content for json+ld and geo MIME types of the global responses relative to errors within the NGSI-LD OAS. --- ngsi-ld-api.yaml | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 3ba565c..5b73578 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -5274,12 +5274,6 @@ components: application/json: schema: $ref: '#/components/schemas/ProblemDetails' - application/json+ld: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/geo: - schema: - $ref: '#/components/schemas/ProblemDetails' MultiStatus.BatchOperationResult: description: | If the entity input data matches to a registration, the relevant parts of the request are forwarded @@ -5330,12 +5324,6 @@ components: application/json: schema: $ref: '#/components/schemas/ProblemDetails' - application/json+ld: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/geo: - schema: - $ref: '#/components/schemas/ProblemDetails' ServiceUnavailable: description: | It is used when re-downloading fails. @@ -5346,12 +5334,6 @@ components: application/json: schema: $ref: '#/components/schemas/ProblemDetails' - application/json+ld: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/geo: - schema: - $ref: '#/components/schemas/ProblemDetails' Unprocessable: description: | It is used to indicate that the operation is not available, @@ -5366,12 +5348,6 @@ components: application/json: schema: $ref: '#/components/schemas/ProblemDetails' - application/json+ld: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/geo: - schema: - $ref: '#/components/schemas/ProblemDetails' NotImplemented: description: | It is used by Registered Context Sources to indicate that the data format @@ -5383,11 +5359,5 @@ components: $ref: '#/components/headers/NGSILD-Warning' content: application/json: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/json+ld: - schema: - $ref: '#/components/schemas/ProblemDetails' - application/geo: schema: $ref: '#/components/schemas/ProblemDetails' \ No newline at end of file -- GitLab From ebe7f840b95a0a337d0ee33e754333c765c79cfa Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 14 Jul 2024 16:58:16 +0200 Subject: [PATCH 105/112] Adding a clarification within the detail property description of the ProblemDetails schema about the InvalidRequest HTTP error (6.3.20 Invalid parameters). --- ngsi-ld-api.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 5b73578..2009342 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -4725,6 +4725,13 @@ components: description: | A human-readable explanation specific to this occurrence of the problem. + + *InvalidRequest: The request associated to the operation is + syntactically invalid or includes wrong content. If an HTTP request + for an operation contains parameters that are incompatible with the + operation, or it contains values of the "options" parameter that are + not supported by the operation, an HTTP error response of type + InvalidRequest should be returned. type: string instance: description: | -- GitLab From 2c79ceb30aa63b399640fe9888ff2c18a320e8ab Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 14 Jul 2024 19:59:06 +0200 Subject: [PATCH 106/112] Fixing minor issues: 1) removing allOf wrapper from previousValue property of the Property schema; 2) removing allOf wrapper from value property of GeoProperty schema; and 3) Considering the VocabularyProperty schema for additionalProperties within Entity schema and for AttributeFragment request body. --- ngsi-ld-api.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 2009342..6ccfd6c 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3202,6 +3202,7 @@ components: - $ref: '#/components/schemas/Relationship' - $ref: '#/components/schemas/GeoProperty' - $ref: '#/components/schemas/LanguageProperty' + - $ref: '#/components/schemas/VocabularyProperty' application/json+ld: schema: allOf: @@ -3214,6 +3215,7 @@ components: - $ref: '#/components/schemas/Relationship' - $ref: '#/components/schemas/GeoProperty' - $ref: '#/components/schemas/LanguageProperty' + - $ref: '#/components/schemas/VocabularyProperty' - required: - '@context' EntityTemporal: @@ -4327,8 +4329,7 @@ components: value: description: | Geolocation encoded as GeoJSON. As mandated by clause 4.7. - allOf: - - $ref: '#/components/schemas/Geometry' + $ref: '#/components/schemas/Geometry' observedAt: description: | Timestamp. See clause 4.8. @@ -4787,10 +4788,9 @@ components: description: | Previous Property value. Only used in notifications, if the showChanges option is explicitly requested. - allOf: - - oneOf: - - $ref: '#/components/schemas/DateTimeValue' - - $ref: '#/components/schemas/AnyValue' + oneOf: + - $ref: '#/components/schemas/DateTimeValue' + - $ref: '#/components/schemas/AnyValue' readOnly: true additionalProperties: oneOf: -- GitLab From 8985de459c46848ee3fc020cbf428f015dce1ecb Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 17 Jul 2024 09:30:21 +0200 Subject: [PATCH 107/112] Fixing the description of externalDocs section of NGSI-LD OAS for describing the name of the ETSI GS CIM 009 document. --- ngsi-ld-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index 6ccfd6c..b434aac 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -10,7 +10,7 @@ info: url: https://forge.etsi.org/legal-matters externalDocs: - description: ETSI GS CIM 009 V1.7.1 cross-cutting Context Information Management (CIM); NGSI-LD API + description: ETSI GS CIM 009 V1.7.1 Context Information Management (CIM); NGSI-LD API url: https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.07.01_60/gs_CIM009v010701p.pdf servers: @@ -3077,7 +3077,7 @@ components: schema: type: array items: - $ref: '#/components/schemas/options.noOverwrite' + $ref: '#/components/schemas/options.noOverwrite' required: false Query.options.sysAttrs: name: options -- GitLab From 53ba3803ab37d57fc320c92de8147f72e6f45f4c Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 22 Sep 2024 19:02:47 +0200 Subject: [PATCH 108/112] Deleting the schema SystemGeneratedAttributes for grouping schemas of system-generated temporal attributes (i.e., createdAt, modifiedAt, and deletedAt) and updating the references to them directly. The problem is that if the schemas of the system-generated temporal attributes are grouped under a schema SystemGeneratedAttributes their data appears with the SystemGeneratedAttributes wrapper when is referenced by another schema or operation. --- ngsi-ld-api.yaml | 115 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 81 insertions(+), 34 deletions(-) diff --git a/ngsi-ld-api.yaml b/ngsi-ld-api.yaml index b434aac..84636fb 100644 --- a/ngsi-ld-api.yaml +++ b/ngsi-ld-api.yaml @@ -3386,22 +3386,6 @@ components: # # Beginning of 4.8 Temporal Properties # - SystemGeneratedAttributes: - description: | - 5.2.2 Common members. - - For grouping the subschemas of system-generated temporal attributes: createdAt, modifiedAt, and deletedAt. - type: object - properties: - createdAt: - $ref: '#/components/schemas/CreatedAt' - readOnly: true - modifiedAt: - $ref: '#/components/schemas/ModifiedAt' - readOnly: true - deletedAt: - $ref: '#/components/schemas/DeletedAt' - readOnly: true CreatedAt: description: | It is defined as the temporal Property at which the Entity, Property or @@ -3744,8 +3728,15 @@ components: to limit unnecessary distributed operation requests. $ref: '#/components/schemas/RegistrationManagementInfo' # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true status: description: | Read-only. Status of the Registration. It shall be "ok" if the last attempt to perform a distributed @@ -3884,8 +3875,15 @@ components: See clause 4.7. $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true additionalProperties: oneOf: - $ref: '#/components/schemas/Property' @@ -3999,8 +3997,15 @@ components: See clause 4.7. $ref: '#/components/schemas/GeoProperty' # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true additionalProperties: oneOf: - type: array @@ -4340,8 +4345,15 @@ components: type: string format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true instanceId: description: | A URI uniquely identifying a Property instance, @@ -4440,8 +4452,15 @@ components: type: string format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true instanceId: description: | A URI uniquely identifying a Property instance, @@ -4775,8 +4794,15 @@ components: type: string format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true instanceId: description: | A URI uniquely identifying a Property instance, @@ -4952,8 +4978,15 @@ components: type: string format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true instanceId: description: | A URI uniquely identifying a Relationship instance @@ -5071,8 +5104,15 @@ components: Language filter to be applied to the query (clause 4.15). type: string # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true status: description: | Read-only. Provided by the system when querying the details of a subscription. @@ -5233,8 +5273,15 @@ components: type: string format: uri # Clause 5.2.2 Common members. System-generated temporal attributes. - systemGeneratedAttrs: - $ref: '#/components/schemas/SystemGeneratedAttributes' + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true instanceId: description: | A URI uniquely identifying a Property instance, -- GitLab From 6eb440551e350911f4907965e4e26c4a5821af43 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 29 Sep 2024 23:40:54 +0200 Subject: [PATCH 109/112] Including two different versions of NGSI-LD OAS release 1.7.1: one for OpenAPI version 3.0.3 and one for OpenAPI version 3.1.0. The OpenAPI version 3.0.3 is recommended to be used by third-party development tools as most of them do not support version 3.1.0 yet. The OpenAPI version 3.1.0 is recommended for reviewing the NGSI-LD OAS documentation and operations. The ReDoc visualization application has been chosen as the solution to navigate the NGSI-LD OAS documentation. --- README.md | 6 +- .../ngsi-ld-api.yaml | 0 openapi-3.1.0/ngsi-ld-api.yaml | 5417 +++++++++++++++++ 3 files changed, 5420 insertions(+), 3 deletions(-) rename ngsi-ld-api.yaml => openapi-3.0.3/ngsi-ld-api.yaml (100%) create mode 100644 openapi-3.1.0/ngsi-ld-api.yaml diff --git a/README.md b/README.md index 3a342b1..caa4b2b 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API spe ### Navigate API -* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) -* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) -* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/ngsi-ld-api.yaml) +* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/openapi-3.0.3/-/raw/1.7.1/ngsi-ld-api.yaml) +* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/openapi-3.0.3/-/raw/1.7.1/ngsi-ld-api.yaml) +* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/openapi-3.1.0/-/raw/1.7.1/ngsi-ld-api.yaml) ## Developers diff --git a/ngsi-ld-api.yaml b/openapi-3.0.3/ngsi-ld-api.yaml similarity index 100% rename from ngsi-ld-api.yaml rename to openapi-3.0.3/ngsi-ld-api.yaml diff --git a/openapi-3.1.0/ngsi-ld-api.yaml b/openapi-3.1.0/ngsi-ld-api.yaml new file mode 100644 index 0000000..948b6e7 --- /dev/null +++ b/openapi-3.1.0/ngsi-ld-api.yaml @@ -0,0 +1,5417 @@ +openapi: 3.1.0 +info: + title: NGSI-LD OAS + version: 1.7.1 + description: OpenAPI Specification for NGSI-LD API. + contact: + url: https://www.etsi.org/committee/cim + license: + name: BSD-3-Clause + url: https://forge.etsi.org/legal-matters + +externalDocs: + description: ETSI GS CIM 009 V1.7.1 Context Information Management (CIM); NGSI-LD API + url: https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.07.01_60/gs_CIM009v010701p.pdf + +servers: + - url: '{protocol}://{hostname}:{port}/ngsi-ld/v1' + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost + port: + default: '443' + +paths: + /entities: + post: + tags: + - Context Information Provision + summary: | + Entity creation + description: | + 5.6.1 Create Entity + + This operation allows creating a new NGSI-LD Entity. + operationId: createEntity + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents the entity that is to be created. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created entity resource. + headers: + Location: + $ref: '#/components/headers/Location' + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Context Information Consumption + summary: | + Query entities + description: | + 5.7.2 Query Entities (excluding batch entity queries). + + This operation allows querying an NGSI-LD system. + operationId: queryEntity + parameters: + # Query params + - $ref: '#/components/parameters/Query.id' + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.idPattern' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.q' + - $ref: '#/components/parameters/Query.csf' + - $ref: '#/components/parameters/Query.geometry' + - $ref: '#/components/parameters/Query.georel' + - $ref: '#/components/parameters/Query.coordinates' + - $ref: '#/components/parameters/Query.geoproperty' + - $ref: '#/components/parameters/Query.geometryProperty' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + - $ref: '#/components/parameters/Query.options.entities' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the query result as a list of entities, unless the Accept Header + indicates that the Entities are to be rendered as GeoJSON. + + If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body + containing the query result as GeoJSON FeatureCollection is returned. + headers: + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + application/geo+json: + schema: + $ref: '#/components/schemas/FeatureCollection' + '400': + $ref: '#/components/responses/BadRequest' + '501': + $ref: '#/components/responses/NotImplemented' + + /entities/{entityId}: + get: + tags: + - Context Information Consumption + summary: | + Entity retrieval by id + description: | + 5.7.1 Retrieve Entity. + + This operation allows retrieving an NGSI-LD Entity. + operationId: retrieveEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.geometryProperty' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.options.entities' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the target entity containing the selected + Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON. + + If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON Feature is returned. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + application/geo+json: + schema: + $ref: '#/components/schemas/Feature' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '501': + $ref: '#/components/responses/NotImplemented' + delete: + tags: + - Context Information Provision + summary: | + Entity deletion by id + description: | + 5.6.6 Delete entity. + + This operation allows deleting an NGSI-LD Entity. + operationId: deleteEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.type' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Information Provision + summary: | + Entity merge by id + description: | + 5.6.17 Merge Entity. + + This operation allows modification of an existing NGSI-LD Entity aligning to the JSON Merge Patch + processing rules defined in IETF RFC 7396 by adding new Attributes (Properties or Relationships) + or modifying or deleting existing Attributes associated with an existing Entity. + operationId: mergeEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.representation' + required: false + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.observedAt' + - $ref: '#/components/parameters/Query.lang' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Attributes to be merged. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - '@context' + responses: + '204': + description: | + All the Attributes were merged successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + put: + tags: + - Context Information Provision + summary: | + Entity replacement by id + description: | + 5.6.18 Replace Entity. + + This operation allows the modification of an existing NGSI-LD Entity + by replacing all of the Attributes (Properties or Relationships). + operationId: replaceEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.type' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Entity to be replaced. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - '@context' + responses: + '204': + description: | + The entity was replaced successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + + /entities/{entityId}/attrs: + post: + tags: + - Context Information Provision + summary: | + Append Attributes to Entity + description: | + 5.6.3 Append Entity Attributes. + + This operation allows modifying an NGSI-LD Entity by adding + new attributes (Properties or Relationships). + operationId: appendAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.options.noOverwrite' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Attributes to be added. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - '@context' + responses: + '204': + description: | + All the Attributes were appended successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + + patch: + tags: + - Context Information Provision + summary: | + Update Attributes of an Entity + description: | + 5.6.2 Update Entity Attributes. + + This operation allows modifying an existing NGSI-LD Entity by updating + already existing Attributes (Properties or Relationships). + operationId: updateEntity + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + - $ref: '#/components/parameters/Query.type' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Entity Fragment containing a complete representation of the Attributes to be updated. + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - '@context' + responses: + '204': + description: | + All the Attributes were appended successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /entities/{entityId}/attrs/{attrId}: + patch: + tags: + - Context Information Provision + summary: | + Partial Attribute Update + description: | + 5.6.4 Partial Attribute Update. + + This operation allows performing a partial update on an NGSI-LD Entity's Attribute (Property or Relationship). + A partial update only changes the elements provided in an Entity Fragment, leaving the rest as they are. + This operation supports the deletion of sub-Attributes but not the deletion of the whole Attribute itself. + operationId: updateAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + - $ref: '#/components/parameters/Query.type' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Attribute Fragment containing the elements of the attribute to be updated. + $ref: '#/components/requestBodies/AttributeFragment' + responses: + '204': + description: | + The attribute was updated successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Information Provision + summary: | + Attribute delete + description: | + 5.6.5 Delete Entity Attribute. + + This operation allows deleting an NGSI-LD Entity's Attribute (Property or Relationship). + The Attribute itself and all its children shall be deleted. + operationId: deleteAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Query params + - $ref: '#/components/parameters/Query.deleteAll' + - $ref: '#/components/parameters/Query.datasetId' + - $ref: '#/components/parameters/Query.type' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + The attribute was deleted successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + put: + tags: + - Context Information Provision + summary: | + Attribute replace + description: | + 5.6.19 Attribute Replace. + + This operation allows the replacement of a single Attribute (Property or Relationship) + within an NGSI-LD Entity. + operationId: replaceAttrs + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + - $ref: '#/components/parameters/Query.type' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Attribute Fragment replacing the previous data. + $ref: '#/components/requestBodies/AttributeFragment' + responses: + '204': + description: | + The attribute was replaced successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + $ref: '#/components/responses/MultiStatus.UpdateResult' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /csourceRegistrations: + post: + tags: + - Context Source Registration + summary: | + Csource registration creation + description: | + 5.9.2 Register Context Source. + + This operation allows registering a context source within an NGSI-LD system. + operationId: createCSR + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents + the context source registration that is to be created. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - type + - information + - endpoint + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - type + - information + - endpoint + - '@context' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created context source registration resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Context Source Discovery + summary: | + Discover Csource registrations + description: | + 5.10.2 Query Context Source Registrations. + + This operation allows discovering context source registrations from an NGSI-LD system. + The behaviour of the discovery of context source registrations differs significantly from + the querying of entities as described in clause 5.7.2. The approach is that the client + submits a query for entities as described in clause 5.7.2, but instead of receiving + the Entity information, it receives a list of Context Source Registrations describing + Context Sources that possibly have some of the requested Entity information. This means + that the requested Entities and Attributes are matched against the 'information' property + as described in clause 5.12. + + If no temporal query is present, only Context Source Registrations for Context Sources + providing latest information, i.e. without specified time intervals, are considered. + If a temporal query is present only Context Source Registrations with matching time intervals, + i.e. observationInterval or managementInterval, are considered. + operationId: queryCSR + parameters: + # Query params + - $ref: '#/components/parameters/Query.id' + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.idPattern' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.q' + - $ref: '#/components/parameters/Query.csf' + - $ref: '#/components/parameters/Query.geometry' + - $ref: '#/components/parameters/Query.georel' + - $ref: '#/components/parameters/Query.coordinates' + - $ref: '#/components/parameters/Query.geoproperty' + - $ref: '#/components/parameters/Query.timeproperty' + - $ref: '#/components/parameters/Query.timerel' + - $ref: '#/components/parameters/Query.timeAt' + - $ref: '#/components/parameters/Query.endTimeAt' + - $ref: '#/components/parameters/Query.geometryProperty' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.options.sysAttrs' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the query result as an array of context source registrations. + headers: + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - id + - type + - information + - endpoint + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - id + - type + - information + - endpoint + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /csourceRegistrations/{registrationId}: + get: + tags: + - Context Source Discovery + summary: | + Csource registration retrieval by id + description: | + 5.10.1 Retrieve Context Source Registration. + + This operation allows retrieving a specific context source registration from an NGSI-LD system. + operationId: retrieveCSR + parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + # Path params + - $ref: '#/components/parameters/Path.registrationId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the target subscription. + headers: + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - id + - type + - information + - endpoint + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - id + - type + - information + - endpoint + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Source Registration + summary: | + Csource registration update by id + description: | + 5.9.3 Update Context Source Registration. + + This operation allows updating a Context Source Registration in an NGSI-LD system. + operationId: updateCSR + parameters: + # Path params + - $ref: '#/components/parameters/Path.registrationId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents + the context source registration that is to be updated. + content: + application/json: + schema: + $ref: '#/components/schemas/CsourceRegistration' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/CsourceRegistration' + - required: + - '@context' + responses: + '204': + description: | + The context source registration was successfully updated. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Source Registration + summary: | + Csource registration deletion by id + description: | + 5.9.4 Delete Context Source Registration. + + This operation allows deleting a Context Source Registration from an NGSI-LD system. + operationId: deleteCSR + parameters: + # Path params + - $ref: '#/components/parameters/Path.registrationId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /subscriptions: + post: + tags: + - Context Information Subscription + summary: | + Create Subscription + description: | + 5.8.1 Create subscription. + + This operation allows creating a new subscription. + operationId: createSubscription + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents the subscription that is to be created. + $ref: '#/components/requestBodies/Subscription' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains the resource URI + of the created subscription resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + get: + tags: + - Context Information Subscription + summary: | + Retrieve list of Subscriptions + description: | + 5.8.4 Query Subscriptions. + + This operation allows querying existing Subscriptions. + operationId: querySubscription + parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing a list of subscriptions. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /subscriptions/{subscriptionId}: + get: + tags: + - Context Information Subscription + summary: | + Subscription retrieval by id + description: | + 5.8.3 Retrieve Subscription. + + This operation allows retrieving an existing subscription. + operationId: retrieveSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the target subscription. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Information Subscription + summary: | + Subscription update by id + description: | + 5.8.2 Update Subscription. + + This operation allows updating an existing subscription. + operationId: updateSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Subscription Fragment including id, type and any other subscription field to be changed. + $ref: '#/components/requestBodies/SubscriptionFragment' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Information Subscription + summary: | + Subscription deletion by id + description: | + 5.8.5 Delete Subscription. + + This operation allows deleting an existing subscription. + operationId: deleteSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /csourceSubscriptions: + post: + tags: + - Context Source Registration Subscription + summary: | + Create subscription to Csource registration + description: | + 5.11.2 Create Context Source Registration Subscription. + + This operation allows creating a new Context Source Registration Subscription. + operationId: createCSRSubscription + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents + the context source registration that is to be created. + $ref: '#/components/requestBodies/Subscription' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created context source registration subscription resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + '409': + $ref: '#/components/responses/Conflict' + get: + tags: + - Context Source Registration Subscription + summary: | + Retrieval of list of subscriptions to Csource registrations + description: | + 5.11.5 Query Context Source Registration Subscriptions. + + This operation allows querying existing Context Source Registration Subscriptions. + operationId: queryCSRSubscription + parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing a list of context source registration subscriptions. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /csourceSubscriptions/{subscriptionId}: + get: + tags: + - Context Source Registration Subscription + summary: | + Csource registration subscription update by id + description: | + 5.11.4 Retrieve Context Source Registration Subscription. + + This operation allows retrieving an existing Context Source Registration Subscription. + operationId: retrieveCSRSubscription + parameters: + # Query params + - $ref: '#/components/parameters/Query.options.sysAttrs' + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of + the target context source registration subscription. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' + - required: + - id + - type + - notification + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + patch: + tags: + - Context Source Registration Subscription + summary: | + Csource registration subscription update by id + description: | + 5.11.3 Update Context Source Registration Subscription. + + This operation allows updating an existing Context Source Registration Subscription. + operationId: updateCSRSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Subscription Fragment including id, type and any other context + source registration subscription field to be changed. + $ref: '#/components/requestBodies/SubscriptionFragment' + responses: + '204': + description: | + The context source registration subscription was successfully updated. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Context Source Registration Subscription + summary: | + Csource registration subscription deletion by id + description: | + 5.11.6 Delete Context Source Registration Subscription. + + This operation allows deleting an existing Context Source Registration Subscription. + operationId: deleteCSRSubscription + parameters: + # Path params + - $ref: '#/components/parameters/Path.subscriptionId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /entityOperations/create: + post: + tags: + - Context Information Provision + summary: | + Batch Entity Creation + description: | + 5.6.7 Batch Entity Creation. + + This operation allows creating a batch of NGSI-LD Entities. + operationId: createBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of entities to be created. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + responses: + '201': + description: | + If all entities have been successfully created, an array of Strings containing URIs + is returned in the response. Each URI represents the Entity Id of a created entity. + There is no restriction as to the order of the Entity Ids. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + type: string + '207': + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + description: | + If only some or none of the entities have been successfully created, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/upsert: + post: + tags: + - Context Information Provision + summary: | + Batch Entity Creation or Update (Upsert) + description: | + 5.6.8 Batch Entity Upsert. + + This operation allows creating a batch of NGSI-LD Entities, updating each of them if they already existed. + In some database jargon this kind of operation is known as "upsert". + operationId: upsertBatch + parameters: + # Query parameters + - $ref: '#/components/parameters/Query.options.upsert' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of entities to be created. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + responses: + '201': + description: | + If all entities not existing prior to this request have been successfully created and + the others have been successfully updated, an array of String (with the URIs representing the + Entity Ids of the created entities only) is returned in the response. There is no restriction as to + the order of the Entity Ids. The merely updated entities do not take part in the response + (corresponding to 204 No Content returned in the case of updates). + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + type: array + items: + type: string + '204': + description: | + If all entities already existed and are successfully updated, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If only some or none of the entities have been successfully created or updated, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created or updated entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created or updated. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/update: + post: + tags: + - Context Information Provision + summary: | + Batch Entity Update + description: | + 5.6.9 Batch Entity Update. + + This operation allows updating a batch of NGSI-LD Entities. + operationId: updateBatch + parameters: + # Query parameters + - $ref: '#/components/parameters/Query.options.noOverwrite' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of entities to be updated. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + responses: + '204': + description: | + If all entities have been successfully updated, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If only some or none of the entities have + been successfully updated, a response + body containing the result of each operation + contained in the batch is returned in a + BatchOperationResult structure. It contains + two arrays. The first array ('success') + contains the URIs of the successfully + updated entities, while the second array + ('errors') contains information about the + error for each of the entities that could not + be updated. There is no restriction as to the + order of the Entity Ids in the arrays. + + If any of the entities matches to a + registration, the relevant parts of the + request are forwarded as a distributed + operation. + + In the case when an error response is + received back from any distributed + operation, a response body containing the + result returned from each registration is + returned in a BatchOperationResult + structure. + + Errors can occur whenever a distributed + operation is unsupported, fails or times out, + see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/delete: + post: + tags: + - Context Information Provision + summary: | + Batch Entity Delete + description: | + 5.6.10 Batch Entity Delete. + + This operation allows deleting a batch of NGSI-LD Entities. + operationId: deleteBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of String (URIs representing Entity IDs) to be deleted. + content: + application/json: + schema: + type: array + items: + type: string + responses: + '204': + description: | + If all entities existed and have been successfully deleted, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If some or all of the entities have not been successfully deleted, or did not exist, + a response body containing the result of each operation contained in the batch is returned + in a BatchOperationResult structure. It contains two arrays. The first array ('success') contains + the URIs of the successfully deleted entities, while the second array ('errors') + contains information about the error for each of the entities that could not be deleted. + There is no restriction as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration is returned + in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, + fails or times out, see clause 6.3.17. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/query: + post: + tags: + - Context Information Consumption + summary: | + Query entities based on POST + description: | + 5.7.2 Query Entity (batch entity queries only). + + This operation allows querying an NGSI-LD system. + operationId: queryBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.count' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.local' + - name: options + in: query + style: form + explode: false + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/options.representation' + - $ref: '#/components/schemas/options.sysAttrs' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Payload body in the request contains a JSON-LD object which represents the query to be performed. + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Query' + - required: + - '@context' + responses: + '200': + description: | + A response body containing the query result as a list of Entities. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + application/geo+json: + schema: + $ref: '#/components/schemas/FeatureCollection' + '400': + $ref: '#/components/responses/BadRequest' + /entityOperations/merge: + post: + tags: + - Context Information Provision + summary: | + Batch Entity Merge + description: | + 5.6.20 Batch Entity Merge. + + This operation allows modification of a batch of NGSI-LD Entities according to the JSON Merge Patch + processing rules defined in IETF RFC 7396 by adding new attributes (Properties or Relationships) + or modifying or deleting existing attributes associated with an existing Entity. + operationId: mergeBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Array of Entities to be merged. + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Entity' + - required: + - id + - type + - '@context' + responses: + '204': + description: | + If all entities have been successfully merged, there is no payload body in the response. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '207': + description: | + If only some or none of the entities have been successfully merged, a response body containing the + result of each operation contained in the batch is returned in a BatchOperationResult structure. + It contains two arrays. The first array ('success') contains the URIs of the successfully created entities, + while the second array ('errors') contains information about the error for each + of the entities that could not be created. There is no restriction + as to the order of the Entity Ids in the arrays. + + If any of the entities matches to a registration, the relevant parts of the request + are forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, + a response body containing the result returned from each registration + is returned in a BatchOperationResult structure. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + $ref: '#/components/responses/MultiStatus.BatchOperationResult' + '400': + $ref: '#/components/responses/BadRequest' + /temporal/entities: + post: + tags: + - Temporal Context Information Provision + summary: | + Temporal Representation of Entity creation + description: | + 5.6.11 Create or Update Temporal Representation of an Entity. + + This operation allows creating or updating (by adding new Attribute instances) + a Temporal Representation of an Entity. + operationId: upsertTemporal + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON-LD object which represents the + temporal representation of the entity that is to be created (or updated). + $ref: '#/components/requestBodies/EntityTemporal' + responses: + '201': + description: | + Upon creation success, the HTTP response shall include a "Location" HTTP header that contains + the resource URI of the created entity resource. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '204': + description: | + Upon update success. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/Unprocessable' + get: + tags: + - Temporal Context Information Consumption + summary: | + Query temporal evolution of Entities + description: | + 5.7.4 Query Temporal Evolution of Entities. + + This operation allows querying the temporal evolution of Entities present in an NGSI-LD system. + It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query. + + *The query parameters timerel and timeAt are required. + operationId: queryTemporal + parameters: + # Query params + - $ref: '#/components/parameters/Query.id' + - $ref: '#/components/parameters/Query.type' + - $ref: '#/components/parameters/Query.idPattern' + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.q' + - $ref: '#/components/parameters/Query.csf' + - $ref: '#/components/parameters/Query.geometry' + - $ref: '#/components/parameters/Query.georel' + - $ref: '#/components/parameters/Query.coordinates' + - $ref: '#/components/parameters/Query.geoproperty' + - $ref: '#/components/parameters/Query.timeproperty' + - $ref: '#/components/parameters/Query.timerel' + - $ref: '#/components/parameters/Query.timeAt' + - $ref: '#/components/parameters/Query.endTimeAt' + - $ref: '#/components/parameters/Query.lastN' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.aggrMethods' + - $ref: '#/components/parameters/Query.aggrPeriodDuration' + - $ref: '#/components/parameters/Query.scopeQ' + - $ref: '#/components/parameters/Query.limit' + - $ref: '#/components/parameters/Query.count' + - $ref: '#/components/parameters/Query.options.temporal' + - $ref: '#/components/parameters/Query.options.sysAttrs' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the query result as a list of temporal representation of Entities. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Results-Count: + $ref: '#/components/headers/NGSILD-Results-Count' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /temporal/entities/{entityId}: + get: + tags: + - Temporal Context Information Consumption + summary: | + Temporal Representation of Entity retrieval by id + description: | + 5.7.3 Retrieve Temporal Evolution of an Entity. + + This operation allows retrieving the temporal evolution of an NGSI-LD Entity. + operationId: retrieveTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Query params + - $ref: '#/components/parameters/Query.attrs' + - $ref: '#/components/parameters/Query.timeproperty' + - $ref: '#/components/parameters/Query.timerel' + - $ref: '#/components/parameters/Query.timeAt' + - $ref: '#/components/parameters/Query.endTimeAt' + - $ref: '#/components/parameters/Query.lastN' + - $ref: '#/components/parameters/Query.lang' + - $ref: '#/components/parameters/Query.aggrMethods' + - $ref: '#/components/parameters/Query.aggrPeriodDuration' + - $ref: '#/components/parameters/Query.options.temporal' + - $ref: '#/components/parameters/Query.options.sysAttrs' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD temporal representation + of the target entity containing the selected Attributes. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Temporal Context Information Provision + summary: | + Temporal Representation of Entity deletion by id + description: | + 5.6.16 Delete Temporal Representation of an Entity. + + This operation allows deleting the Temporal Representation of an Entity. + operationId: deleteTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entities/{entityId}/attrs: + post: + tags: + - Temporal Context Information Provision + summary: | + Temporal Representation of Entity Attribute instance addition + description: | + 5.6.12 Add Attributes to Temporal Representation of an Entity. + + This operation allows modifying a Temporal Representation of an Entity by adding new Attribute instances. + operationId: appendAttrsTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + EntityTemporal Fragment containing a complete representation of the Attribute instances to be added. + $ref: '#/components/requestBodies/EntityTemporalFragment' + responses: + '204': + description: | + All the Attributes were added successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entities/{entityId}/attrs/{attrId}: + delete: + tags: + - Temporal Context Information Provision + summary: | + Attribute from Temporal Representation of Entity deletion + description: | + 5.6.13 Delete Attributes from Temporal Representation of an Entity. + + This operation allows deleting an Attribute (Property or Relationship) of the Temporal Representation of an Entity. + The Attribute itself and all its children shall be deleted. + operationId: deleteAttrsTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + # Query params + - $ref: '#/components/parameters/Query.deleteAll' + - $ref: '#/components/parameters/Query.datasetId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + The attribute was deleted successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entities/{entityId}/attrs/{attrId}/{instanceId}: + patch: + tags: + - Temporal Context Information Provision + summary: | + Attribute Instance update + description: | + 5.6.14 Partial Update Attribute instance in Temporal Representation of an Entity. + + This operation allows modifying a specific Attribute (Property or Relationship) instance, + identified by its instanceId, of a Temporal Representation of an Entity. + + This operation enables the correction of wrong information that could have been previously added + to the Temporal Representation of an Entity. + operationId: updateAttrsTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + - $ref: '#/components/parameters/Path.instanceId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced. + $ref: '#/components/requestBodies/EntityTemporalFragment' + responses: + '204': + description: | + The attribute was updated successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + delete: + tags: + - Temporal Context Information Provision + summary: | + Attribute Instance deletion by instance id + description: | + 5.6.15 Delete Attribute Instance from Temporal Representation of an Entity. + + This operation allows deleting one Attribute instance (Property or Relationship), + identified by its instanceId, of a Temporal Representation of an Entity. + The Attribute itself and all its child elements shall be deleted. This operation enables + the removal of individual Attribute instances that could have been previously added + to the Temporal Representation of an Entity. + operationId: deleteAttrInstanceTemporal + parameters: + # Path params + - $ref: '#/components/parameters/Path.entityId' + - $ref: '#/components/parameters/Path.attrId' + - $ref: '#/components/parameters/Path.instanceId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + The attribute instance was delete successfully. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /temporal/entityOperations/query: + post: + tags: + - Temporal Context Information Consumption + summary: | + Temporal Representation of Entity Query based on POST + description: | + 5.7.4 Query Temporal Evolution of Entities. + + This operation allows querying the temporal evolution of Entities present in an NGSI-LD system. + It is similar to the operation defined by clause 5.7.2 (Query Entities) with the addition of a temporal query. + operationId: temporalQueryBatch + parameters: + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: Payload body in the request contains a JSON-LD object which represents the query to be performed. + $ref: '#/components/requestBodies/QueryTemporal' + responses: + '200': + description: | + A response body containing the query result as a list of Entities. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + application/json+ld: + schema: + type: array + items: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + - '@context' + '400': + $ref: '#/components/responses/BadRequest' + /types: + get: + tags: + - Context Information Consumption + summary: | + Retrieve available entity types + description: | + 5.7.5 Retrieve Available Entity Types. + + This operation allows retrieving a list of NGSI-LD entity types for which + entity instances exist within the NGSI-LD system. + + 5.7.6 Retrieve Details of Available Entity Types. + + This operation allows retrieving a list with a detailed representation of + NGSI-LD entity types for which entity instances exist within the NGSI-LD system. + operationId: retrieveEntityTypes + parameters: + # Query params + - name: details + in: query + description: | + If true, then detailed entity type information represented as an array with + elements of the Entity Type data structure (clause 5.2.25) is to be returned. + style: form + explode: true + schema: + type: boolean + required: false + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the EntityTypeList + (clause 5.2.24) is to be returned, unless details=true is specified. + + If details=true is specified, a response body containing a JSON-LD array + with elements of the EntityType data structure (clause 5.2.25) is to be returned. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/EntityTypeList' + - type: array + items: + $ref: '#/components/schemas/EntityType' + application/json+ld: + schema: + oneOf: + - allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTypeList' + - type: array + items: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityType' + '400': + $ref: '#/components/responses/BadRequest' + /types/{type}: + get: + tags: + - Context Information Consumption + summary: | + Details about available entity type + description: | + 5.7.7 Retrieve Available Entity Type information. + + This operation allows retrieving detailed entity type information about a specified NGSI-LD entity + type for which entity instances exist within the NGSI-LD system. The detailed representation includes + the type name (as short name if available in the provided @context), the count of available entity + instances and details about attributes that existing instances of this entity type have, including + their name (as short name if available in the provided @context) and a list of types the attribute + can have (e.g. Property, Relationship or GeoProperty). + operationId: retrieveEntityTypeInfo + parameters: + # Path params + - $ref: '#/components/parameters/Path.type' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of + the detailed information about the available entity type. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + $ref: '#/components/schemas/EntityTypeInfo' + application/json+ld: + schema: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTypeInfo' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /attributes: + get: + tags: + - Context Information Consumption + summary: | + Available attributes + description: | + 5.7.8 Retrieve Available Attributes. + + This operation allows retrieving a list of NGSI-LD attributes that belong to + entity instances existing within the NGSI- LD system. + + 5.7.9 Retrieve Details of Available Attributes. + + This operation allows retrieving a list with a detailed representation of NGSI-LD + attributes that belong to entity instances existing within the NGSI-LD system. + operationId: retrieveAttrTypes + parameters: + # Query params + - name: details + in: query + description: | + If true, then detailed attribute information represented as an array + with elements of the Attribute data structure (clause 5.2.28) is to be returned. + style: form + explode: true + schema: + type: boolean + required: false + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of the AttributeList + (clause 5.2.27) is to be returned, unless details=true is specified. + + If details=true is specified, a response body containing a JSON-LD array + with elements of the Attribute data structure (clause 5.2.28) is to be returned. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/AttributeList' + - type: array + items: + $ref: '#/components/schemas/Attribute' + application/json+ld: + schema: + oneOf: + - allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/AttributeList' + - type: array + items: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Attribute' + '400': + $ref: '#/components/responses/BadRequest' + /attributes/{attrId}: + get: + tags: + - Context Information Consumption + summary: | + Details about available attribute + description: | + 5.7.10 Retrieve Available Attribute Information. + + This operation allows retrieving detailed attribute information about a specified NGSI-LD attribute + that belongs to entity instances existing within the NGSI-LD system. The detailed representation includes + the attribute name (as short name if available in the provided @context) and the type names + for which entity instances exist that have the respective attribute, a count of available + attribute instances and a list of types the attribute can have (e.g. Property, Relationship or GeoProperty). + operationId: retrieveAttrTypeInfo + parameters: + # Path params + - $ref: '#/components/parameters/Path.attrId' + # Local Query param + - $ref: '#/components/parameters/Query.local' + # Request headers + - $ref: '#/components/parameters/Headers.Link' + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing the JSON-LD representation of + the detailed information about the available attribute. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + $ref: '#/components/schemas/Attribute' + application/json+ld: + schema: + allOf: + - type: object + required: + - '@context' + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Attribute' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + /jsonldContexts: + post: + tags: + - JSON-LD Context API + summary: | + Add a user @context to the internal cache + description: | + 5.13.2 Add @context. + + With this operation, a client can ask the Broker to store the full content + of a specific @context, by giving it to the Broker. + operationId: createContext + parameters: + - $ref: '#/components/parameters/Headers.ngsildTenant' + requestBody: + description: | + Payload body in the request contains a JSON object that has a root node named @context, + which represents a JSON-LD "local" context. + content: + application/json: + schema: + type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + required: + - '@context' + application/json+ld: + schema: + type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + required: + - '@context' + responses: + '201': + description: | + The HTTP response shall include a "Location" HTTP header that contains the + local URI of the added @context. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + '400': + $ref: '#/components/responses/BadRequest' + get: + tags: + - JSON-LD Context API + summary: | + List all cached @contexts + description: | + 5.13.3 List @contexts. + + With this operation a client can obtain a list of URLs that represent all of the @contexts + stored in the local context store of the Broker. Each URL can be used to download the + corresponding @context, and, in case the @context's kind is "Cached", it shall be + the original URL the Broker downloaded the @context from. + + In case a "details" flag is set to true, the client obtains a list of JSON objects, + each representing information (metadata) about an @context currently stored by the Broker. + Each JSON object contains information about the @context's original URL (if any), its + local identifier in the Broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"), + its creation timestamp, its expiry date (if "Cached"), and additional optional information. + operationId: listContexts + parameters: + # Query params + - $ref: '#/components/parameters/Query.details' + - $ref: '#/components/parameters/Query.kind' + # Request headers + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + A response body containing a list of URLs or a list of JSON Objects, as defined in clause 5.13.3.5, + representing metadata about stored @contexts. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + oneOf: + - type: array + items: + type: string + format: uri + - type: array + items: + $ref: '#/components/schemas/LdContextMetadata' + application/json+ld: + schema: + oneOf: + - type: array + items: + type: string + format: uri + - type: array + items: + $ref: '#/components/schemas/LdContextMetadata' + '400': + $ref: '#/components/responses/BadRequest' + /jsonldContexts/{contextId}: + get: + tags: + - JSON-LD Context API + summary: | + Serve one specific user @context + description: | + 5.13.4 Serve @context. + + With this operation a client can obtain the full content of a specific @context + (only for @contexts of kind "Hosted" or "ImplicitlyCreated"), which is currently + stored in the Broker's internal storage, or its metadata (for all kinds of stored @contexts). + operationId: retrieveContext + parameters: + # Path params + - $ref: '#/components/parameters/Path.contextId' + # Query params + - $ref: '#/components/parameters/Query.details' + # Request headers + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '200': + description: | + 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". + If the parameter details is True, response body contains a JSON object as defined + in clause 5.13.4.5, which metadata of a JSON-LD "local context". + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + oneOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/LdContextMetadata' + application/json+ld: + schema: + oneOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/LdContextMetadata' + '400': + $ref: '#/components/responses/BadRequest' + '404': + description: | + It is used when a client provided an + @context identifier not known to the + system, see clause 6.3.2. + $ref: '#/components/responses/NotFound' + '422': + description: | + It is used when a client indicated an + @context of type "Cached", see + clause 6.3.2. + $ref: '#/components/responses/Unprocessable' + delete: + tags: + - JSON-LD Context API + summary: | + Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it + description: | + 5.13.5 Delete and Reload @context + + With this operation, a client supplies a local identifier to the Broker, indicating + a stored @context, that the Broker shall remove from its storage. For @contexts of + kind "Cached" this can also be the original URL the Broker downloaded the @context from. + If the entry in the local storage that corresponds to the identifier is itself + an array of @contexts, this operation will not delete the children, + i.e. the @contexts in the array, but just the entry. + operationId: deleteContext + parameters: + # Path params + - $ref: '#/components/parameters/Path.contextId' + # Query params + - $ref: '#/components/parameters/Query.reload' + # Request headers + - $ref: '#/components/parameters/Headers.ngsildTenant' + responses: + '204': + description: | + No Content. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + '400': + $ref: '#/components/responses/BadRequest' + '404': + description: | + It is used when a client provided an + @context identifier not known to the + system, see clause 6.3.2. + $ref: '#/components/responses/NotFound' + '503': + description: | + It is used when re-downloading fails. + $ref: '#/components/responses/ServiceUnavailable' + +components: + headers: + Location: + description: | + Contains the resource URI of the created entity resource. + schema: + type: string + NGSILD-Results-Count: + description: | + 6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned. + schema: + type: integer + NGSILD-Tenant: + description: | + 6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted. + schema: + type: string + NGSILD-Warning: + description: | + 6.3.17 Distributed Operations Caching and Timeout Behaviour + schema: + type: string + enum: + - '110 - Response is Stale' + - '111 - Revalidation Failed' + - '199 - Miscellaneous Warning' + - '299 - Miscellaneous Persistent Warning' + required: false + parameters: + Headers.Link: + name: Link + in: header + description: | + 6.3.5 JSON-LD @context resolution + + In summary, from a developer's perspective, for POST, PATCH and PUT operations, + if MIME type is "application/ld+json", then the associated @context shall be provided + only as part of the request payload body. Likewise, if MIME type is "application/json", + then the associated @context shall be provided only by using the JSON-LD Link header. + No mixes are allowed, i.e. mixing options shall result in HTTP response errors. + Implementations should provide descriptive error messages when these situations arise. + + In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header. + explode: true + schema: + type: string + format: uri + Headers.ngsildTenant: + name: NGSILD-Tenant + in: header + description: | + 6.3.14 Tenant specification. The tenant to which the NGSI-LD HTTP operation is targeted. + explode: true + schema: + type: string + Path.attrId: + name: attrId + in: path + description: | + Name of the attribute for which detailed information is to be retrieved. + The Fully Qualified Name (FQN) as well as the short name can be used, + given that the latter is part of the JSON-LD @context provided. + schema: + $ref: '#/components/schemas/Path' + required: true + Path.contextId: + name: contextId + in: path + description: | + Local identifier of the @context to be managed (served or deleted). For @contexts of kind "Cached" + this can also be the original URL the Broker downloaded the @context from. + schema: + $ref: '#/components/schemas/Path' + required: true + Path.entityId: + name: entityId + in: path + description: Id (URI) of the entity to be retrieved. + schema: + $ref: '#/components/schemas/Path' + required: true + Path.instanceId: + name: instanceId + in: path + description: Id (URI) identifying a particular Attribute instance. + schema: + $ref: '#/components/schemas/Path' + required: true + Path.registrationId: + name: registrationId + in: path + description: Id (URI) of the context source registration. + schema: + $ref: '#/components/schemas/Path' + required: true + Path.subscriptionId: + name: subscriptionId + in: path + description: Id (URI) of the concerned subscription. + schema: + $ref: '#/components/schemas/Path' + required: true + Path.type: + name: type + in: path + description: | + Name of the entity type for which detailed information is to be retrieved. + The Fully Qualified Name (FQN) as well as the short name can be used, + given that the latter is part of the JSON-LD @context provided. + schema: + $ref: '#/components/schemas/Path' + required: true + Query.aggrMethods: + name: aggrMethods + in: query + description: | + 4.5.19.1 Aggregated Temporal Representation of an Entity. + + Comma separated list of aggregation methods. + + Only applicable if aggregatedValues is present in the options parameter. + style: form + explode: false + schema: + type: string + enum: + - 'totalCount' + - 'distinctCount' + - 'sum' + - 'avg' + - 'min' + - 'max' + - 'stddev' + - 'sumsq' + required: false + Query.aggrPeriodDuration: + name: aggrPeriodDuration + in: query + description: | + If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning + the whole time range specified by the temporal query. + + Only applicable if aggregatedValues is present in the options parameter. + style: form + explode: false + schema: + type: string + default: '0' + required: false + Query.attrs: + name: attrs + in: query + description: | + List of Attributes to be matched by the Entity and included in the response. If the Entity does not + have any of the Attributes in attrs, then a 404 Not Found shall be retrieved. If attrs is not + specified, no matching is performed and all Attributes related to the Entity shall be retrieved. + style: form + explode: false + schema: + type: array + items: + type: string + required: false + Query.coordinates: + name: coordinates + in: query + description: | + Coordinates serialized as a string as per clause 4.10. It is part of geoquery. + It shall be one if geometry or georel are present. + style: form + explode: true + schema: + oneOf: + - $ref: '#/components/schemas/Geometry.position' + - $ref: '#/components/schemas/Geometry.positionArray' + - $ref: '#/components/schemas/Geometry.lineString' + - $ref: '#/components/schemas/Geometry.linearRing' + - $ref: '#/components/schemas/Geometry.polygon' + required: false + Query.count: + name: count + in: query + description: | + 6.3.13 Counting number of results. If true, then a special HTTP header (NGSILD-Results-Count) is set in + the response. Regardless of how many entities are actually returned (maybe due to the "limit" URI parameter), + the total number of matching results (e.g. number of Entities) is returned. + style: form + explode: true + schema: + type: boolean + required: false + Query.csf: + name: csf + in: query + description: Context Source filter as per clause 4.9. + style: form + explode: true + schema: + type: string + required: false + Query.datasetId: + name: datasetId + in: query + description: | + Specifies the datasetId of the dataset to be deleted. + style: form + explode: true + schema: + type: string + format: uri + required: false + Query.details: + name: details + in: query + description: Whether a list of URLs or a more detailed list of JSON Objects is requested. + style: form + explode: true + schema: + type: boolean + required: false + Query.deleteAll: + name: deleteAll + in: query + description: | + If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified + by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, + the default Attribute instance is deleted. + style: form + explode: true + schema: + type: boolean + required: false + Query.endTimeAt: + name: endTimeAt + in: query + description: | + It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between". + String representing the endTimeAt parameter as defined by clause 4.11. + style: form + explode: true + schema: + type: string + format: date-time + required: false + Query.id: + name: id + in: query + description: List of entity ids to be retrieved. + style: form + explode: false + schema: + type: array + items: + type: string + format: uri + required: false + Query.idPattern: + name: idPattern + in: query + description: Regular expression that shall be matched by entity ids. + style: form + explode: true + schema: + type: string + format: pattern + required: false + Query.geometryProperty: + name: geometryProperty + in: query + description: | + 4.5.16.1 Top-level "geometry" field selection algorithm. + A parameter of the request (named "geometryProperty") may be used to indicate the name of the GeoProperty to be selected. + If this parameter is not present, then the default name of "location" shall be used. + + In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use + for the toplevel geometry field. + style: form + explode: true + schema: + type: string + required: false + Query.geometry: + name: geometry + in: query + description: | + Geometry as per clause 4.10. It is part of geoquery. It shall be one if geometry or georel are present. + style: form + explode: true + schema: + type: string + enum: + - Point + - MultiPoint + - LineString + - MultiLineString + - Polygon + - MultiPolygon + required: false + Query.geoproperty: + name: geoproperty + in: query + description: | + The name of the Property that contains the geospatial data that will be used to resolve the geoquery. + By default, will be location (see clause 4.7). It shall be ignored unless a geoquery is present. + style: form + explode: true + schema: + type: string + enum: + - location + - observationSpace + - operationSpace + default: location + required: false + Query.georel: + name: georel + in: query + description: | + Geo relationship as per clause 4.10. It is part of geoquery. It shall be one if + geometry or georel are present. + style: form + explode: true + schema: + oneOf: + - type: string + enum: + - equals + - disjoint + - intersects + - within + - contains + - overlaps + - type: string + pattern: ^near;((maxDistance==\\d+)|(minDistance==\\d+))$ + required: false + Query.kind: + name: kind + in: query + description: | + Can be either "Cached", "Hosted", or "ImplicitlyCreated". + style: form + explode: true + schema: + type: string + enum: + - Cached + - Hosted + - ImplicitlyCreated + required: false + Query.lang: + name: lang + in: query + description: | + It is used to reduce languageMaps to a string or string array property in a single preferred language. + style: form + explode: true + schema: + type: string + required: false + Query.lastN: + name: lastN + in: query + description: | + Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. + style: form + explode: true + schema: + type: integer + minimum: 1 + required: false + Query.limit: + name: limit + in: query + description: | + 6.3.10 Pagination behaviour. It defines the limit to the number of NGSI-LD Elements that shall be retrieved + at a maximum as mandated by clause 5.5.9. The value 0 is only allowed in combination with + the count URI parameter. + style: form + explode: true + schema: + type: integer + minimum: 0 + required: false + Query.local: + name: local + in: query + description: | + 6.3.18 Limiting Distributed Operations. If local=true then no Context Source Registrations shall be + considered as matching to avoid cascading distributed operations (see clause 4.3.6.4). + style: form + explode: true + schema: + type: boolean + required: false + Query.observedAt: + name: observedAt + in: query + description: | + When a merge operation applies to a pre-existing Attribute which previously contained an "observedAt" + sub-attribute, the value held in this query parameter shall be used if no specific "observedAt" + sub-Attribute is found in the payload body. + schema: + type: string + format: date-time + required: false + Query.options.entities: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + anyOf: + - $ref: '#/components/schemas/options.representation' + - $ref: '#/components/schemas/options.sysAttrs' + required: false + Query.options.noOverwrite: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.noOverwrite' + required: false + Query.options.sysAttrs: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.sysAttrs' + required: false + Query.options.temporal: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.temporal' + required: false + Query.options.upsert: + name: options + in: query + style: form + explode: false + schema: + type: array + items: + $ref: '#/components/schemas/options.upsert' + required: false + Query.q: + name: q + in: query + description: | + Query as per clause 4.9. + style: form + explode: true + schema: + type: string + required: false + Query.reload: + name: reload + in: query + description: | + Indicates to perform a download and replace of the @context, as specified in clause 5.13.5.4. + style: form + explode: true + schema: + type: boolean + required: false + Query.scopeQ: + name: scopeQ + in: query + description: | + Scope query (see clause 4.19). + style: form + explode: true + schema: + type: string + required: false + Query.timeAt: + name: timeAt + in: query + description: | + It shall be a DateTime. Cardinality shall be 1 if timerel is present. + String representing the timeAt parameter as defined by clause 4.11. + style: form + explode: true + schema: + type: string + format: date-time + required: false + Query.timeproperty: + name: timeproperty + in: query + description: | + Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". + If not specified, the default is "observedAt". (See clause 4.8) + style: form + explode: true + schema: + type: string + enum: + - observedAt + - createdAt + - modifiedAt + - deletedAt + default: observedAt + required: false + Query.timerel: + name: timerel + in: query + description: | + Allowed values: "before", "after", "between" + style: form + explode: true + schema: + type: string + enum: + - before + - after + - between + required: false + Query.type: + name: type + in: query + description: | + Selection of Entity Types as per clause 4.17. + style: form + explode: true + schema: + type: string + required: false + requestBodies: + AttributeFragment: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - $ref: '#/components/schemas/VocabularyProperty' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - oneOf: + - $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - $ref: '#/components/schemas/VocabularyProperty' + - required: + - '@context' + EntityTemporal: + content: + application/json: + schema: + $ref: '#/components/schemas/EntityTemporal' + required: + - id + - type + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' + - required: + - id + - type + - '@context' + EntityTemporalFragment: + content: + application/json: + schema: + $ref: '#/components/schemas/EntityTemporal' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/EntityTemporal' + - required: + - '@context' + QueryTemporal: + content: + application/json: + schema: + $ref: '#/components/schemas/Query.temporal' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Query.temporal' + - required: + - '@context' + Subscription: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - required: + - type + - notification + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' + - required: + - type + - notification + - '@context' + SubscriptionFragment: + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + application/json+ld: + schema: + allOf: + - type: object + properties: + '@context': + $ref: '#/components/schemas/LdContext' + - $ref: '#/components/schemas/Subscription' + - required: + - '@context' + schemas: + AnyValue: + description: Any JSON value as defined by IETF RFC 8259. + ### + # Beginning of Options parameters + # + options.noOverwrite: + description: | + 6.16.3 For POST method associated to the operations "Batch Entity Update" and "Append Entity Attributes", the "noOvevwrite" + options query parameter indicates that no attribute overwrite shall be performed. + type: string + enum: + - noOverwrite + options.representation: + description: | + 6.3.7 Representation of Entities. + + When its value includes the keyword "normalized", a normalized + representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned + in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2 and 4.5.18.2. + + When its value includes the keyword "concise", a concise lossless representation of Entities shall + be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as + defined in clauses 4.5.2.3, 4.5.3.3 and 4.5.18.3. In this case the broker will return data in the + most concise lossless representation possible, for example removing all Attribute "type" members. + + When its value includes the keyword "keyValues" (or "simplified" as a synonym), a simplified + representation of Entities shall be provided as defined by clause 4.5.4. + + If the Accept Header is set to "application/geo+json" the response will be in simplified GeoJSON + format as defined by clause 4.5.17. + type: string + enum: + - normalized + - concise + - keyValues + - simplified + options.sysAttrs: + description: | + 6.3.11 Including system generated attributes. + + When its value includes the keyword "sysAttrs", a representation of NGSI-LD Elements shall be + provided so that the system generated attributes createdAt, modifiedAt are included in the response + payload body. In the case of temporal representations, also the system generated attribute deletedAt + is included, if the NGSI-LD Element has been deleted. + type: string + enum: + - sysAttrs + options.temporal: + description: | + 6.3.12 Simplified or aggregated temporal representation of entities. + + When its value includes the keyword "temporalValues", a simplified temporal representation of + entities shall be provided as defined by clause 4.5.8. + + When its value includes the keyword "aggregatedValues", an aggregated temporal representation of + entities shall be provided as defined by clause 4.5.19. + + Only one of the two keywords can be present in the values of the parameter. + type: string + enum: + - temporalValues + - aggregatedValues + options.upsert: + description: | + 6.15.3 Upsert configuration. + + "replace". Indicates that all the existing Entity content shall be replaced (default mode); + + "update". Indicates that existing Entity content shall be updated. + type: string + enum: + - replace + - update + default: replace + # + # End of Options parameters + ### + ### + # + # Beginning of 4.8 Temporal Properties + # + CreatedAt: + description: | + It is defined as the temporal Property at which the Entity, Property or + Relationship was entered into an NGSI-LD system. + + Entity creation timestamp. See clause 4.8. + type: string + format: date-time + ModifiedAt: + description: | + It is defined as the temporal Property at which the Entity, Property or Relationship + was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value. + + Entity last modification timestamp. See clause 4.8. + type: string + format: date-time + DeletedAt: + description: | + It is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system. + + Entity deletion timestamp. See clause 4.8. It is only used in notifications reporting deletions and in the + Temporal Representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8) + and LanguageProperties (clause 5.2.32). + type: string + format: date-time + ObservedAt: + description: | + It is defined as the temporal Property at which a certain Property or Relationship became valid or was observed. + For example, a temperature Value was measured by the sensor at this point in time. + type: string + format: date-time + # + # End of 4.8 Temporal Properties + ### + Attribute: + description: | + 5.2.28 This type represents the data needed to define the attribute information. + type: object + properties: + id: + description: | + Full URI of attribute name. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - Attribute + attributeName: + description: | + Name of the attribute, short name if contained in @context. + type: string + attributeCount: + description: | + Number of attribute instances with this attribute name. + type: number + attributeTypes: + description: | + List of attribute types (e.g. Property, Relationship, GeoProperty) for which + entity instances exist, which contain an attribute with this name. + type: array + items: + type: string + typeNames: + description: | + List of entity type names for which entity instances exist containing + attributes that have the respective name. + type: array + items: + type: string + required: + - id + - type + - attributeName + AttributeList: + description: | + 5.2.27 This type represents the data needed to define the attribute + list representation as mandated by clause 4.5.13. + type: object + properties: + id: + description: | + Unique identifier for the attribute list. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - AttributeList + attributeList: + description: | + List containing the attribute names. + type: array + items: + type: string + required: + - id + - type + - attributeList + BatchEntityError: + description: | + 5.2.17 This datatype represents an error raised (associated to a particular Entity) during + the execution of a batch or distributed operation. + type: object + properties: + entityId: + description: | + Entity Id corresponding to the Entity in error. + type: string + format: uri + registrationId: + description: | + Registration Id corresponding to a failed distributed operation (optional). + type: string + format: uri + error: + description: | + One instance per Entity in error. + $ref: '#/components/schemas/ProblemDetails' + required: + - entityId + - error + BatchOperationResult: + description: | + 5.2.16 The datatype represents the result of a batch operation. + type: object + properties: + success: + description: | + Array of Entity Ids corresponding to the Entities that were successfully + treated by the concerned operation. + type: array + items: + type: string + format: uri + errors: + description: | + One array item per Entity in error. + type: array + items: + $ref: '#/components/schemas/BatchEntityError' + required: + - success + - errors + CsourceNotification: + description: | + 5.3.2 This datatype represents the parameters that allow building a Context Source Notification + to be sent to a subscriber. + type: object + properties: + id: + description: | + Csource notification identifier (JSON-LD @id). + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - CsourceNotification + subscriptionId: + description: | + Identifier of the subscription that originated the notification. + type: string + format: uri + notifiedAt: + description: | + Timestamp corresponding to the instant when the notification was generated by the system. + type: string + format: date-time + data: + description: | + The content of the notification as NGSI-LD entities. See clause 5.2.4. + type: array + items: + $ref: '#/components/schemas/CsourceRegistration' + readOnly: true + triggerReason: + description: | + Indicates whether the Csources in the CsourceRegistration.Input(s) in data are newly matching + (initial notification or creation), have been updated (but still match) or do not match any longer. + + • "newlyMatching" - describes the case that the notified Context Source Registration(s) newly + match(es) the identified subscription. This value is used in the first notification and + whenever a new Context Source Registration matching the Subscription has been registered, + or an existing Context Source Registration that did not match before has been updated + in such a way that it matches now. + + • "updated" - describes the case that the notified Context Source Registration that + was part of a previous notification has been updated, but still matches the Subscription. + + • "noLongerMatching" - describes the case that the notified Context Source Registration + that was part of a previous notification no longer matches the Subscription, i.e. as a result of + an update or because it was deleted. + type: string + enum: + - newlyMatching + - updated + - noLongerMatching + required: + - id + - type + - subscriptionId + - notifiedAt + - data + - triggerReason + CsourceRegistration: + description: | + 5.2.9 This type represents the data needed to register a new Context Source. + type: object + properties: + id: + description: | + Unique registration identifier. (JSON-LD @id). There may be multiple registrations per + Context Source, i.e. the id is unique per registration. + type: string + format: uri + type: + description: | + JSON-LD @type Use reserved type for identifying Context Source Registration. + type: string + enum: + - ContextSourceRegistration + registrationName: + description: | + A name given to this Context Source Registration. + type: string + minLength: 1 + description: + description: | + A description of this Context Source Registration. + type: string + minLength: 1 + information: + description: | + Describes the Entities, Properties and Relationships for which the + Context Source may be able to provide information. + type: array + items: + $ref: '#/components/schemas/RegistrationInfo' + minItems: 1 + tenant: + description: | + Identifies the tenant that has to be specified in all requests to the Context Source that + are related to the information registered in this Context Source Registration. + If not present, the default tenant is assumed. Should only be present in systems supporting multi-tenancy. + type: string + observationInterval: + description: | + If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity + information is also provided, a separate Context Registration is needed for this purpose). + The observationInterval specifies the time interval for which the Context Source can provide + Entity information as specified by the observedAt Temporal Property. + A temporal query based on the observedAt Temporal Property, which is the default, + is matched against the observationInterval for overlap. + $ref: '#/components/schemas/TimeInterval' + managementInterval: + description: | + If present, the Context Source can be queried for Temporal Entity Representations. (If latest Entity + information is also provided, a separate Context Registration is needed for this purpose). + The managementInterval specifies the time interval for which the Context Source can provide Entity + information as specified by the createdAt, modifiedAt and deletedAt Temporal Properties. + A temporal query based on the createdAt, modifiedAt or deletedAt Temporal Property is matched + against the managementInterval for overlap. + $ref: '#/components/schemas/TimeInterval' + location: + description: | + Location for which the Context Source may be able to provide information. + $ref: '#/components/schemas/Geometry' + observationSpace: + description: | + Geographic location that includes the observation spaces of all entities as specified by their + respective observationSpace GeoProperty for which the Context Source may be able to provide + information. + $ref: '#/components/schemas/Geometry' + operationSpace: + description: | + Geographic location that includes the operation spaces of all entities as specified by their + respective operationSpace GeoProperty for which the Context Source may be able to provide + information. + $ref: '#/components/schemas/Geometry' + expiresAt: + description: | + Provides an expiration date. When passed the Context Source Registration + will become invalid and the Context Source might no longer be available. + type: string + format: date-time + endpoint: + description: | + Endpoint expressed as dereferenceable URI through which the Context Source exposes its NGSI-LD interface. + type: string + format: uri + contextSourceInfo: + description: | + Generic {key, value} array to convey optional information to provide + when contacting the registered Context Source. + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + scope: + description: | + Scopes (see clause 4.18) for which the Context Source has Entities. + oneOf: + - type: string + - type: array + items: + type: string + mode: + description: | + The definition of the mode of distributed operation (see clause 4.3.6) + supported by the registered Context Source. + type: string + enum: + - inclusive + - exclusive + - redirect + - auxiliary + default: inclusive + operations: + description: | + The definition limited subset of API operations supported by the registered Context Source. + + If undefined, the default set of operations is "federationOps" (see clause 4.20). + type: array + items: + type: string + refreshRate: + description: | + An indication of the likely period of time to elapse between updates at this registered endpoint. + Brokers may optionally use this information to help implement caching. + type: string + management: + description: | + Holds additional optional registration management information that can be used + to limit unnecessary distributed operation requests. + $ref: '#/components/schemas/RegistrationManagementInfo' + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + status: + description: | + Read-only. Status of the Registration. It shall be "ok" if the last attempt to perform a distributed + operation succeeded. It shall be "failed" if the last attempt to perform a distributed operation failed. + type: string + enum: + - ok + - failed + readOnly: true + timesSent: + description: | + Number of times that the registration triggered a distributed operation, including failed attempts. + type: number + minimum: 0 + readOnly: true + timesFailed: + description: Number of times that the registration triggered a distributed operation request that failed. + type: number + minimum: 0 + readOnly: true + lastSuccess: + description: | + Timestamp corresponding to the instant when the last successfully distributed operation was sent. + Created on first successful operation. + type: string + format: date-time + readOnly: true + lastFailure: + description: | + Timestamp corresponding to the instant when the last distributed operation resulting in + a failure (for instance, in the HTTP binding, an HTTP response code other than 2xx) was returned. + type: string + format: date-time + readOnly: true + additionalProperties: + $ref: '#/components/schemas/AnyValue' + DateTimeValue: + description: | + Date representation as mandated by C.6 "Date Representation". + type: object + properties: + '@type': + type: string + enum: + - DateTime + default: DateTime + '@value': + type: string + format: date-time + required: + - '@type' + - '@value' + Endpoint: + description: | + 5.2.15 This datatype represents the parameters that are required in order to define an endpoint for notifications. + type: object + properties: + uri: + description: | + URI which conveys the endpoint which will receive the notification. + type: string + format: uri + accept: + description: | + Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). + If not present, default is "application/json". + type: string + enum: + - application/json + - application/ld+json + - application/geo+json + timeout: + description: | + Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed. + The NGSI-LD system can override this value. This only applies if the binding protocol always returns a + response. + type: number + minimum: 1 + cooldown: + description: | + Once a failure has occurred, minimum period of time in milliseconds which shall elapse before + attempting to make a subsequent notification to the same endpoint after failure. + If requests are received before the cooldown period has expired, no notification is sent. + type: number + minimum: 1 + receiverInfo: + description: | + Generic {key, value} array to convey optional information to the receiver. + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + notifierInfo: + description: | + Generic {key, value} array to set up the communication channel. + type: array + items: + $ref: '#/components/schemas/KeyValuePair' + required: + - uri + Entity: + description: | + 5.2.4 NGSI-LD Entity. + type: object + properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. + oneOf: + - type: string + - type: array + items: + type: string + scope: + description: | + Scope. + oneOf: + - type: string + - type: array + items: + type: string + location: + description: | + Default geospatial Property of an entity. See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + observationSpace: + description: | + See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + operationSpace: + description: | + See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - type: array + items: + $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - type: array + items: + $ref: '#/components/schemas/LanguageProperty' + - $ref: '#/components/schemas/VocabularyProperty' + - type: array + items: + $ref: '#/components/schemas/VocabularyProperty' + EntityInfo: + description: | + 5.2.8 This type represents what Entities, Entity Types or group of Entity ids + (as a regular expression pattern mandated by IEEE 1003.2TM) can be provided (by Context Sources). + type: object + properties: + id: + description: | + Entity identifier. + type: string + format: uri + idPattern: + description: | + A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. + type: string + format: pattern + type: + description: | + Entity Type (or JSON array, in case of Entities with multiple Entity Types). + oneOf: + - type: string + - type: array + items: + type: string + required: + - type + EntitySelector: + description: | + 5.2.33 This type selects which entity or group of entities are queried or subscribed to by Context Consumers. + The `id` takes precedence over `idPattern`. + type: object + properties: + id: + description: | + Entity identifier. + type: string + format: uri + idPattern: + description: | + A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities. + type: string + format: pattern + type: + description: | + Selector of Entity Type(s). + type: string + required: + - type + EntityTemporal: + description: | + 5.2.20 This is the same data type as mandated by clause 5.2.4 with the only deviation that + the representation of Properties and Relationships shall be the temporal one + (arrays of (Property or Relationship) instances represented by JSON-LD objects) + as defined in clauses 4.5.7 and 4.5.8. Alternatively it is possible to specify + the EntityTemporal by using the "Simplified Temporal Representation of an Entity", + as defined in clause 4.5.9. + properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed. + oneOf: + - type: string + - type: array + items: + type: string + scope: + description: | + Scope. + oneOf: + - type: string + - type: array + items: + type: string + location: + description: | + Default geospatial Property of an entity. See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + observationSpace: + description: | + See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + operationSpace: + description: | + See clause 4.7. + $ref: '#/components/schemas/GeoProperty' + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + additionalProperties: + oneOf: + - type: array + items: + $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/GeoProperty' + - type: array + items: + $ref: '#/components/schemas/LanguageProperty' + - type: array + items: + $ref: '#/components/schemas/VocabularyProperty' + EntityType: + description: | + 5.2.25 This type represents the data needed to define the elements of the detailed + entity type list representation as mandated by clause 4.5.11. + type: object + properties: + id: + description: | + Fully Qualified Name (FQN) of the entity type being described. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - EntityType + typeName: + description: | + Name of the entity type, short name if contained in @context. + type: string + attributeNames: + description: | + List containing the names of attributes that instances of the entity type can have. + type: array + items: + type: string + required: + - id + - type + - typeName + - attributeNames + EntityTypeInfo: + description: | + 5.2.26 This type represents the data needed to define the detailed entity type + information representation as mandated by clause 4.5.12. + type: object + properties: + id: + description: | + Fully Qualified Name (FQN) of the entity type being described. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - EntityTypeInfo + typeName: + description: | + Name of the entity type, short name if contained in @context. + type: string + entityCount: + description: | + Number of entity instances of this entity type. + type: number + attributeDetails: + description: | + List of attributes that entity instances with the specified entity type can have. + type: array + items: + $ref: '#/components/schemas/Attribute' + required: + - id + - type + - typeName + - entityCount + - attributeDetails + EntityTypeList: + description: | + 5.2.24 This type represents the data needed to define the entity type + list representation as mandated by clause 4.5.10. + type: object + properties: + id: + description: | + Unique identifier for the entity type list. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - EntityTypeList + typeList: + description: | + List containing the entity type names. + type: array + items: + type: string + required: + - id + - type + - typeList + Feature: + description: | + 5.2.29 This data type represents a spatially bounded Entity in GeoJSON format, as mandated by IETF RFC 7946. + type: object + properties: + id: + description: | + Entity id. + type: string + format: uri + type: + description: | + GeoJSON Type. + type: string + enum: + - Feature + geometry: + description: | + Null if no matching GeoProperty. + $ref: '#/components/schemas/Geometry' + properties: + description: | + List of attributes as mandated by clause 5.2.31. + $ref: '#/components/schemas/FeatureProperties' + '@context': + description: | + JSON-LD @context. This field is only present if requested in the payload by + the HTTP Prefer Header (IETF RFC 7240). + $ref: '#/components/schemas/LdContext' + required: + - id + - type + - geometry + - properties + FeatureCollection: + description: | + 5.2.30 This data type represents a list of spatially bounded + Entities in GeoJSON format, as mandated by IETF RFC 7946. + type: object + properties: + type: + description: | + GeoJSON Type. + type: string + enum: + - FeatureCollection + features: + description: | + In the case that no matches are found, "features" will be an empty array. + type: array + items: + $ref: '#/components/schemas/Feature' + '@context': + description: | + JSON-LD @context. This field is only present if requested in the payload + by the HTTP Prefer Header (IETF RFC 7240). + $ref: '#/components/schemas/LdContext' + required: + - type + FeatureProperties: + description: | + 5.2.31 This data type represents the type and the associated attributes + (Properties and Relationships) of an Entity in GeoJSON format. + type: object + properties: + type: + description: | + Entity Type (or JSON array, in case of Entities with multiple Entity Types). + Both short hand string (type name) or URI are allowed. + oneOf: + - type: string + - type: array + items: + type: string + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + - $ref: '#/components/schemas/GeoProperty' + - type: array + items: + $ref: '#/components/schemas/GeoProperty' + - $ref: '#/components/schemas/LanguageProperty' + - type: array + items: + $ref: '#/components/schemas/LanguageProperty' + required: + - type + ###### + # Geometry schemas (BEGIN) + # + Geometry.position: + description: | + A single position. + type: array + minItems: 2 + maxItems: 3 + items: + type: number + Geometry.positionArray: + description: | + An array of positions. + type: array + items: + $ref: '#/components/schemas/Geometry.position' + Geometry.lineString: + description: | + An array of two or more positions. + allOf: + - $ref: '#/components/schemas/Geometry.positionArray' + - minItems: 2 + Geometry.linearRing: + description: | + An array of four positions where the first equals the last (i.e., a closed LineString). + allOf: + - $ref: '#/components/schemas/Geometry.positionArray' + - minItems: 4 + Geometry.polygon: + description: | + An array of linear rings. + type: array + items: + $ref: '#/components/schemas/Geometry.linearRing' + Geometry.Point: + type: object + properties: + type: + type: string + enum: + - Point + coordinates: + $ref: '#/components/schemas/Geometry.position' + Geometry.MultiPoint: + type: object + properties: + type: + type: string + enum: + - MultiPoint + coordinates: + $ref: '#/components/schemas/Geometry.positionArray' + Geometry.Polygon: + type: object + properties: + type: + type: string + enum: + - Polygon + coordinates: + $ref: '#/components/schemas/Geometry.polygon' + Geometry.LineString: + type: object + properties: + type: + type: string + enum: + - LineString + coordinates: + $ref: '#/components/schemas/Geometry.lineString' + Geometry.MultiLineString: + type: object + properties: + type: + type: string + enum: + - MultiLineString + coordinates: + type: array + items: + $ref: '#/components/schemas/Geometry.lineString' + Geometry.MultiPolygon: + type: object + properties: + type: + type: string + enum: + - MultiPolygon + coordinates: + type: array + items: + $ref: '#/components/schemas/Geometry.lineString' + Geometry: + description: | + A valid GeoJSON geometry object (as mandated by RFC7946). + oneOf: + - $ref: '#/components/schemas/Geometry.Point' + - $ref: '#/components/schemas/Geometry.MultiPoint' + - $ref: '#/components/schemas/Geometry.Polygon' + - $ref: '#/components/schemas/Geometry.LineString' + - $ref: '#/components/schemas/Geometry.MultiLineString' + - $ref: '#/components/schemas/Geometry.MultiPolygon' + # + # Geometry schemas (END) + ###### + GeoProperty: + description: | + 5.2.7 NGSI-LD GeoProperty. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - GeoProperty + default: GeoProperty + value: + description: | + Geolocation encoded as GeoJSON. As mandated by clause 4.7. + $ref: '#/components/schemas/Geometry' + observedAt: + description: | + Timestamp. See clause 4.8. + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + previousValue: + description: | + Previous GeoProperty value. Only used in notifications, if the showChanges + option is explicitly requested. + $ref: '#/components/schemas/Geometry' + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + GeoQuery: + description: | + 5.2.13 This datatype represents a geoquery used for Subscriptions. + type: object + properties: + # Could be of Geometry schema type + geometry: + description: | + Type of the reference geometry. + type: string + coordinates: + description: | + Coordinates of the reference geometry. For the sake of JSON-LD compatibility. + It can be encoded as a string as described in clause 4.7.1. + # To be checked + oneOf: + - type: string + - type: array + items: + type: object + georel: + description: | + Geo-relationship (near, within, etc.). + type: string + geoproperty: + description: | + Specifies the GeoProperty to which the GeoQuery is to be applied. + If not present, the default GeoProperty is location. + type: string + required: + - geometry + - coordinates + - georel + KeyValuePair: + description: | + 5.2.22 This datatype represents the optional information that is required when contacting an endpoint for notifications. + type: object + properties: + key: + description: | + The key of the key/value pair. + type: string + value: + description: | + The value of the key/value pair. + type: string + required: + - key + - value + LanguageProperty: + description: | + 5.2.32 NGSI-LD LanguageProperty. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - LanguageProperty + default: LanguageProperty + languageMap: + description: | + String Property Values defined in multiple natural languages. + type: object + observedAt: + description: | + Timestamp. See clause 4.8. + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + previousLanguageMap: + description: | + Previous Language Property languageMap. Only used in notifications, if the showChanges + option is explicitly requested. + type: object + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + LdContext: + description: | + 5.2.3 JSON-LD @context + + When encoding NGSI-LD Entities, Context Source Registrations, Subscriptions and Notifications, + as pure JSON-LD (MIME type "application/ld+json"), a proper @context shall be included + as a special member of the corresponding JSON-LD Object. + oneOf: + - type: string + format: uri + - type: object + - type: array + items: + oneOf: + - type: string + format: uri + - type: object + LdContextMetadata: + description: | + JSON object which represents information (metadata) + about an @context currently stored by the Broker as defined in 5.13.3.5. It contains information about the @context's + original URL (if any), its local identifier in the Broker's storage, its kind ("Cached", "Hosted" and "ImplicitlyCreated"), + its creation timestamp, its expiry date (if "Cached"), and additional optional information. + type: array + items: + type: object + properties: + "URL": + type: string + format: uri + "localId": + type: string + format: uri + "kind": + type: string + enum: + - Cached + - Hosted + - ImplicitlyCreated + "timestamp": + type: string + format: date-time + "lastUsage": + type: string + format: date-time + "numberOfHits": + type: integer + "extraInfo": + type: object + required: + - "URL" + - "localId" + - "kind" + - "timestamp" + NotUpdatedDetails: + description: | + 5.2.19 This datatype represents additional information provided by an implementation + when an Attribute update did not happen. + type: object + properties: + attributeName: + description: | + Attribute name. + type: string + reason: + description: | + Reason for not having changed such Attribute. + type: string + registrationId: + description: | + Registration Id corresponding to a failed distributed operation (optional). + type: string + format: uri + required: + - attributeName + - reason + Notification: + description: | + 5.3.1 This datatype represents the parameters that allow building a notification to be sent to a subscriber. + type: object + properties: + id: + description: | + Notification identifier (JSON-LD @id). It shall be automatically generated by the implementation. + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - Notification + subscriptionId: + description: | + Identifier of the subscription that originated the notification. + type: string + format: uri + notifiedAt: + description: | + Timestamp corresponding to the instant when the notification was generated by the system. + type: string + format: date-time + data: + description: | + The content of the notification as NGSI-LD Entities. See clause 5.2.4. + + If the notification has been triggered from a Subscription that has the notification. + endpoint.accept field set to application/geo+json then data is returned as a FeatureCollection. + In this case, if the notification.endpoint.rece iverInfo contains the key "Prefer" and + it is set to the value "body=json", then the FeatureCollection will not contain + an @context field. + + If endpoint.accept is not set or holds another value then Entity[] is returned. + oneOf: + - type: array + items: + $ref: '#/components/schemas/Entity' + - $ref: '#/components/schemas/FeatureCollection' + required: + - id + - type + - subscriptionId + - notifiedAt + - data + NotificationParams: + description: | + 5.2.14 This datatype represents the parameters that allow to convey the details of a notification. + type: object + properties: + attributes: + description: | + Entity Attribute Names (Properties or Relationships) to be included in the notification payload body. + If undefined it will mean all Attributes. + type: array + items: + type: string + minItems: 1 + sysAttrs: + description: | + If true, the system generated attributes createdAt and modifiedAt are included in + the response payload body, in the case of a deletion also deletedAt. + type: boolean + default: false + format: + description: | + Conveys the representation format of the entities delivered at notification time. + By default, it will be in the normalized format. + type: string + enum: + - normalized + - concise + - keyValues + showChanges: + description: | + If true the previous value (previousValue) of Properties or languageMap (previousLanguageMap) of + Language Properties or object (previousObject) of Relationships is provided in addition to the current one. + This requires that it exists, i.e. in case of modifications and deletions, + but not in the case of creations. showChanges cannot be true in case format is "keyValues". + type: boolean + default: false + endpoint: + description: | + Notification endpoint details. + $ref: '#/components/schemas/Endpoint' + status: + description: | + Status of the Notification. It shall be "ok" if the last attempt to notify the subscriber succeeded. + It shall be "failed" if the last attempt to notify the subscriber failed. + type: string + enum: + - ok + - failed + timesSent: + description: | + Number of times that the notification has been sent. Provided by the system when + querying the details of a subscription. + type: number + minimum: 1 + timesFailed: + description: | + Number of times an unsuccessful response (or timeout) has been received when deliverying the notification. + Provided by the system when querying the details of a subscription. + type: number + minimum: 1 + lastNotification: + description: | + Timestamp corresponding to the instant when the last notification has been sent. + Provided by the system when querying the details of a subscription. + type: string + format: date-time + lastFailure: + description: | + Timestamp corresponding to the instant when the last notification resulting in failure + (for instance, in the HTTP binding, an HTTP response code different than 200) has been sent. + Provided by the system when querying the details of a subscription. + type: string + format: date-time + lastSuccess: + description: | + Timestamp corresponding to the instant when the last successful (200 OK response) notification + has been sent. Provided by the system when querying the details of a subscription. + type: string + format: date-time + required: + - endpoint + Path: + description: Common schema for URI data type in path parameters. + type: string + format: uri + ###### + # "ProblemDetails" schema from ETSI NFV OAS (BEGIN) + # + ProblemDetails: + description: | + The definition of the general "ProblemDetails" data structure from + IETF RFC 7807 is reproduced inthis structure. Compared to the + general framework defined in IETF RFC 7807, the "status" and + "detail" attributes are mandated to be included by the present document, + to ensure that the response contains additional textual information about + an error. IETF RFC 7807 foresees extensibility of the + "ProblemDetails" type. It is possible that particular APIs in the present + document, or particular implementations, define extensions to define + additional attributes that provide more information about the error. + The description column only provides some explanation of the meaning to + Facilitate understanding of the design. For a full description, see + IETF RFC 7807. + type: object + required: + - status + - detail + properties: + type: + description: | + A URI reference according to IETF RFC 3986 that identifies the + problem type. It is encouraged that the URI provides human-readable + documentation for the problem (e.g. using HTML) when dereferenced. + When this member is not present, its value is assumed to be + "about:blank". + type: string + format: URI + title: + description: | + A short, human-readable summary of the problem type. It should not + change from occurrence to occurrence of the problem, except for + purposes of localization. If type is given and other than + "about:blank", this attribute shall also be provided. + A short, human-readable summary of the problem + type. It SHOULD NOT change from occurrence to occurrence of the + problem, except for purposes of localization (e.g., using + proactive content negotiation; see [RFC7231], Section 3.4). + type: string + status: + description: | + The HTTP status code for this occurrence of the problem. + The HTTP status code ([RFC7231], Section 6) generated by the origin + server for this occurrence of the problem. + type: integer + detail: + description: | + A human-readable explanation specific to this occurrence of the + problem. + + *InvalidRequest: The request associated to the operation is + syntactically invalid or includes wrong content. If an HTTP request + for an operation contains parameters that are incompatible with the + operation, or it contains values of the "options" parameter that are + not supported by the operation, an HTTP error response of type + InvalidRequest should be returned. + type: string + instance: + description: | + A URI reference that identifies the specific occurrence of the + problem. It may yield further information if dereferenced. + type: string + format: URI + # + # "ProblemDetails" schema from ETSI NFV OAS (END) + ###### + Property: + description: | + 5.2.5 NGSI-LD Property. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - Property + default: Property + value: + description: | + Property value. + oneOf: + - $ref: '#/components/schemas/DateTimeValue' + - $ref: '#/components/schemas/AnyValue' + observedAt: + description: | + Timestamp. See clause 4.8. + $ref: '#/components/schemas/ObservedAt' + unitCode: + description: | + Property Value's unit code. + type: string + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + previousValue: + description: | + Previous Property value. Only used in notifications, if the showChanges + option is explicitly requested. + oneOf: + - $ref: '#/components/schemas/DateTimeValue' + - $ref: '#/components/schemas/AnyValue' + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + Query: + description: | + 5.2.23 This datatype represents the information that is required in order to convey + a query when a "Query Entities" operation is to be performed (as per clause 5.7.2). + type: object + properties: + type: + description: | + JSON-LD @type. + type: string + enum: + - Query + entities: + description: | + Entity ids, id pattern and Entity types that shall be matched by Entities in order to be retrieved. + type: array + items: + $ref: '#/components/schemas/EntitySelector' + minItems: 1 + attrs: + description: | + List of Attributes that shall be matched by Entities in order to be retrieved. + If not present all Attributes will be retrieved. + type: array + items: + type: string + minItems: 1 + q: + description: | + Query that shall be matched by Entities in order to be retrieved. + type: string + geoQ: + description: | + Geoquery that shall be matched by Entities in order be retrieved. + $ref: '#/components/schemas/GeoQuery' + csf: + description: | + Context source filter that shall be matched by Context Source Registrations describing + Context Sources to be used for retrieving Entities. + type: string + #temporalQ: + # description: | + # Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). + # $ref: '#/components/schemas/TemporalQuery' + scopeQ: + description: Scope query. + type: string + lang: + description: Language filter to be applied to the query (clause 4.15). + type: string + required: + - type + Query.temporal: + description: | + 5.2.23 This datatype represents the information that is required in order to convey + a query when a "Query Temporal Evolution of Entities" operation is to be performed (as pe clause 5.7.4). + allOf: + - $ref: '#/components/schemas/Query' + - type: object + properties: + temporalQ: + description: | + Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4). + $ref: '#/components/schemas/TemporalQuery' + - required: + - temporalQ + RegistrationInfo: + description: | + 5.2.10 RegistrationInfo. + type: object + properties: + entities: + description: | + Describes the entities for which the CSource may be able to provide information. + type: array + items: + $ref: '#/components/schemas/EntityInfo' + minItems: 1 + propertyNames: + description: | + Describes the Properties that the CSource may be able to provide. + type: array + items: + type: string + minItems: 1 + relationshipNames: + description: | + Describes the Relationships that the CSource may be able to provide. + type: array + items: + type: string + minItems: 1 + RegistrationManagementInfo: + description: | + 5.2.34 This type represents the data to alter the default behaviour of a Context Broker when + making a distributed operation request to a registered Context Source. + type: object + properties: + localOnly: + description: | + If localOnly=true then distributed operations associated to this Context Source Registration + will act only on data held directly by the registered Context Source itself (see clause 4.3.6.4). + type: boolean + cacheDuration: + description: | + Minimal period of time which shall elapse between two consecutive context information + consumption operations (as defined in clause 5.7) related to the same context data will occur. + If the cacheDuration latency period has not been reached, a cached value for the + entity or its attributes shall be returned where available. + type: string + timeout: + description: | + Maximum period of time in milliseconds which may elapse before a + forwarded request is assumed to have failed. + type: number + minimum: 1 + cooldown: + description: | + Minimum period of time in milliseconds which shall elapse before attempting + to make a subsequent forwarded request to the same endpoint after failure. + If requests are received before the cooldown period has expired, a timeout error + response for the registration is automatically returned. + type: number + minimum: 1 + Relationship: + description: | + 5.2.6 NGSI-LD Relationship. + properties: + type: + description: | + Node type. + type: string + enum: + - Relationship + default: Relationship + object: + description: | + Relationship's target object. + type: string + format: uri + observedAt: + description: | + Timestamp. See clause 4.8. + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of target relationship objects. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Relationship instance + (see clause 4.5.8). System generated. + type: string + format: uri + readOnly: true + previousObject: + description: | + Previous Relationship's target object. Only used in notifications, if the showChanges + option is explicitly requested. + type: string + format: uri + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + Subscription: + oneOf: + - $ref: '#/components/schemas/Subscription.OnChange' + - $ref: '#/components/schemas/Subscription.Periodic' + Subscription.Common: + description: | + 5.2.12 This datatype represents a Context Subscription. + type: object + properties: + id: + description: | + Subscription identifier (JSON-LD @id). + type: string + format: uri + type: + description: | + JSON-LD @type. + type: string + enum: + - Subscription + subscriptionName: + description: | + A (short) name given to this Subscription. + type: string + description: + description: | + Subscription description. + type: string + entities: + description: | + Entities subscribed. + type: array + items: + $ref: '#/components/schemas/EntitySelector' + minItems: 1 + notificationTrigger: + description: | + The notification triggers listed indicate what kind of changes shall trigger a notification. + If not present, the default is the combination attributeCreated and attributeUpdated. + entityUpdated is equivalent to the combination attributeCreated, attributeUpdated and attributeDeleted. + type: array + items: + type: string + enum: + - entityCreated + - entityUpdated + - entityDeleted + - attributeCreated + - attributeUpdated + - attributeDeleted + q: + description: | + Query that shall be met by subscribed entities in order to trigger the notification. + type: string + geoQ: + description: | + Geoquery that shall be met by subscribed entities in order to trigger the notification. + $ref: '#/components/schemas/GeoQuery' + csf: + description: | + Context source filter that shall be met by Context Source Registrations describing Context Sources + to be used for Entity Subscriptions. + type: string + isActive: + description: | + Allows clients to temporarily pause the subscription by making it inactive. + true indicates that the Subscription is under operation. + false indicates that the subscription is paused and notifications shall not be delivered. + type: boolean + default: true + notification: + description: | + Notification details. + $ref: '#/components/schemas/NotificationParams' + expiresAt: + description: | + Expiration date for the subscription. + type: string + format: date-time + temporalQ: + description: | + Temporal Query to be used only in Context Registration Subscriptions for matching + Context Source Registrations of Context Sources providing temporal information. + $ref: '#/components/schemas/TemporalQuery' + scopeQ: + description: | + Scope query. + type: string + lang: + description: | + Language filter to be applied to the query (clause 4.15). + type: string + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + status: + description: | + Read-only. Provided by the system when querying the details of a subscription. + type: string + enum: + - active + - paused + - expired + readOnly: true + jsonldContext: + description: | + The dereferenceable URI of the JSON-LD @context to be used when sending + a notification resulting from the subscription. If not provided, the + @context used for the subscription shall be used as a default. + type: string + format: uri + Subscription.Periodic: + allOf: + - $ref: '#/components/schemas/Subscription.Common' + - type: object + properties: + timeInterval: + description: | + Indicates that a notification shall be delivered periodically regardless of attribute changes. + Actually, when the time interval (in seconds) specified in this value field is reached. + type: number + minimum: 1 + Subscription.OnChange: + allOf: + - $ref: '#/components/schemas/Subscription.Common' + - type: object + properties: + watchedAttributes: + description: | + Watched Attributes (Properties or Relationships). If not defined it means any Attribute. + type: array + items: + type: string + minItems: 1 + throttling: + description: | + Minimal period of time in seconds which shall elapse between two consecutive notifications. + type: number + minimum: 1 + TemporalQuery: + description: | + 5.2.21 This datatype represents a temporal query. + type: object + properties: + timerel: + description: | + Allowed values: "before", "after" and "between". + type: string + enum: + - before + - after + - between + timeAt: + description: | + It shall be a DateTime. + type: string + format: date-time + endTimeAt: + description: | + It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between". + type: string + format: date-time + timeproperty: + description: | + Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". + If not specified, the default is "observedAt". (See clause 4.8). + type: string + enum: + - observedAt + - createdAt + - modifiedAt + - deletedAt + default: observedAt + required: + - timerel + - timeAt + TimeInterval: + description: | + 5.2.11 NGSI-LD TimeInterval. + type: object + properties: + startAt: + description: | + Describes the start of the time interval. + type: string + format: date-time + endAt: + description: | + Describes the end of the time interval. If not present the interval is open. + type: string + format: date-time + required: + - startAt + UpdateResult: + description: | + 5.2.18 This datatype represents the result of Attribute update (append or update) operations + in the NGSI-LD API regardless of whether local or distributed. + type: object + properties: + updated: + description: | + List of Attributes (represented by their Name) that were appended or updated. + type: array + items: + type: string + notUpdated: + description: | + List which contains the Attributes (represented by their Name) that were not updated, + together with the reason for not being updated. + type: array + items: + $ref: '#/components/schemas/NotUpdatedDetails' + required: + - updated + - notUpdated + VocabularyProperty: + description: | + 5.2.35 NGSI-LD VocabularyProperty. + type: object + properties: + type: + description: | + Node type. + type: string + enum: + - VocabularyProperty + default: VocabularyProperty + vocab: + description: | + String Values which shall be type coerced to URIs based on the supplied @context. + oneOf: + - type: string + - type: array + items: + type: string + previousVocab: + description: | + Previous Vocabulary Property vocab. Only used in notifications, if the showChanges + option is explicitly requested. + oneOf: + - type: string + - type: array + items: + type: string + readOnly: true + observedAt: + description: | + Timestamp. See clause 4.8. + $ref: '#/components/schemas/ObservedAt' + datasetId: + description: | + It allows identifying a set or group of property values. + type: string + format: uri + # Clause 5.2.2 Common members. System-generated temporal attributes. + createdAt: + $ref: '#/components/schemas/CreatedAt' + readOnly: true + modifiedAt: + $ref: '#/components/schemas/ModifiedAt' + readOnly: true + deletedAt: + $ref: '#/components/schemas/DeletedAt' + readOnly: true + instanceId: + description: | + A URI uniquely identifying a Property instance, + as mandated by (see clause 4.5.7). System generated. + type: string + format: uri + readOnly: true + additionalProperties: + oneOf: + - $ref: '#/components/schemas/Property' + - type: array + items: + $ref: '#/components/schemas/Property' + - $ref: '#/components/schemas/Relationship' + - type: array + items: + $ref: '#/components/schemas/Relationship' + + responses: + BadRequest: + description: | + It is used to indicate that the request or its content is incorrect, + see clause 6.3.2. In the returned ProblemDetails structure, the "detail" + attribute should convey more information about the error. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + Conflict: + description: | + It is used to indicate that the entity or an exclusive or redirect + registration defining the entity already exists, see clause 6.3.2. + In the returned ProblemDetails structure, the "detail" attribute should + convey more information about the error. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + MultiStatus.BatchOperationResult: + description: | + If the entity input data matches to a registration, the relevant parts of the request are forwarded + as a distributed operation. In the case when an error response is received back from any distributed + operation, a response body containing the result returned from each registration is returned in a + BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, + fails or times out, see clause 6.3.17. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + Location: + $ref: '#/components/headers/Location' + content: + application/json: + schema: + $ref: '#/components/schemas/BatchOperationResult' + MultiStatus.UpdateResult: + description: | + Only the Attributes included in the response payload body were successfully appended. If no Attributes + were successfully updated the updated array of UpdateResult (see clause 5.2.18) will be empty. + + If the entity input data matches to a registration, the relevant parts of the request are + forwarded as a distributed operation. + + In the case when an error response is received back from any distributed operation, a response + body containing the result returned from each registration is returned in a UpdateResult structure. + + Names of the Attributes included in the UpdateResult structure are represented as Fully Qualified Names as per clause 6.3.6. + + Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateResult' + NotFound: + description: | + It is used when a client provided an entity identifier (URI) not known + to the system, see clause 6.3.2. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + ServiceUnavailable: + description: | + It is used when re-downloading fails. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + Unprocessable: + description: | + It is used to indicate that the operation is not available, + see clause 6.3.2. In the returned ProblemDetails structure, + the "detail" attribute should convey more information about the error. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' + NotImplemented: + description: | + It is used by Registered Context Sources to indicate that the data format + of the request is unsupported see clause 6.3.7. + headers: + NGSILD-Tenant: + $ref: '#/components/headers/NGSILD-Tenant' + NGSILD-Warning: + $ref: '#/components/headers/NGSILD-Warning' + content: + application/json: + schema: + $ref: '#/components/schemas/ProblemDetails' \ No newline at end of file -- GitLab From 843b6471b020f7ededdd3e7b88a632a390d77fa4 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Sun, 29 Sep 2024 23:43:34 +0200 Subject: [PATCH 110/112] Fixing the hyperlinks to NGSI-LD OAS within the Navigate API section of the README file. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index caa4b2b..0038daa 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API spe ### Navigate API -* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/openapi-3.0.3/-/raw/1.7.1/ngsi-ld-api.yaml) -* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/openapi-3.0.3/-/raw/1.7.1/ngsi-ld-api.yaml) -* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/openapi-3.1.0/-/raw/1.7.1/ngsi-ld-api.yaml) +* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/openapi-3.0.3/ngsi-ld-api.yaml) +* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/openapi-3.0.3/ngsi-ld-api.yaml) +* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/openapi-3.1.0/ngsi-ld-api.yaml) ## Developers -- GitLab From 5dac8ec97f671f42c78240bdebb33fba338aaa46 Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Thu, 3 Oct 2024 10:08:07 +0200 Subject: [PATCH 111/112] Updating references to NGSI-LD meta-model schemas within sample custom schemas. --- .../iot-sensors-custom-schemas.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/examples/customSchemas/iot-sensors-custom-schemas.yaml b/examples/customSchemas/iot-sensors-custom-schemas.yaml index 9ca61c2..071ea10 100644 --- a/examples/customSchemas/iot-sensors-custom-schemas.yaml +++ b/examples/customSchemas/iot-sensors-custom-schemas.yaml @@ -11,7 +11,7 @@ components: description: | NGSI-LD Entity Type that represents a temperature sensor. allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Entity' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Entity' - type: object properties: type: @@ -29,7 +29,7 @@ components: description: | NGSI-LD Property Type. The temperature measurement. allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Property' - type: object properties: value: @@ -41,7 +41,7 @@ components: description: | NGSI-LD Entity Type that represents a humidity sensor. allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Entity' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Entity' - type: object properties: type: @@ -59,7 +59,7 @@ components: description: | NGSI-LD Property Type. The humidity measurement. allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Property' - type: object properties: value: @@ -71,7 +71,7 @@ components: description: | NGSI-LD Entity Type that represents an IoT device. allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Entity' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Entity' - type: object properties: type: @@ -95,7 +95,7 @@ components: description: NGSI-LD Property Type. The IoT device name. additionalProperties: false allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Property' - type: object properties: value: @@ -106,7 +106,7 @@ components: description: NGSI-LD Property Type. The IoT device description. additionalProperties: false allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Property' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Property' - type: object properties: value: @@ -119,7 +119,7 @@ components: NGSI-LD Relationship Type to identify a temperature sensor of the IoT device (i.e., the identifier of an NGSI-LD Entity of type TemperatureSensor). allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Relationship' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Relationship' - type: object properties: object: @@ -132,7 +132,7 @@ components: NGSI-LD Relationship Type to identify a humidity sensor of the IoT device (i.e., the identifier of an NGSI-LD Entity of type HumiditySensor). allOf: - - $ref: '../../ngsi-ld-api.yaml#/components/schemas/Relationship' + - $ref: '../../openapi-3.0.3/ngsi-ld-api.yaml#/components/schemas/Relationship' - type: object properties: object: -- GitLab From 7e39ec18bfbfacc5b22001b1d3dee645db23df5e Mon Sep 17 00:00:00 2001 From: daniel-gonzalez-sanchez Date: Wed, 9 Oct 2024 09:49:47 +0200 Subject: [PATCH 112/112] Fixing the hyperlinks to NGSI-LD OAS within the Navigate API section of the README file in order to point out the stable version of OAS. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0038daa..f5c8b0f 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ This repository contains the OpenAPI Specification (OAS) for the NGSI-LD API spe ### Navigate API -* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/openapi-3.0.3/ngsi-ld-api.yaml) -* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/openapi-3.0.3/ngsi-ld-api.yaml) -* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/1.7.1/openapi-3.1.0/ngsi-ld-api.yaml) +* [Swagger UI](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/v1.7.1/openapi-3.0.3/ngsi-ld-api.yaml) +* [Swagger Editor](https://forge.etsi.org/swagger/editor/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/v1.7.1/openapi-3.0.3/ngsi-ld-api.yaml) +* [Redocly](https://redocly.github.io/redoc/?url=https://forge.etsi.org/rep/cim/ngsi-ld-openapi/-/raw/v1.7.1/openapi-3.1.0/ngsi-ld-api.yaml) ## Developers -- GitLab