openapi: 3.0.3 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'