openapi: 3.0.3 info: description: This OAS file describes the NGSI-LD API defined by the ETSI ISG CIM group. This Cross-domain Context Information Management API allows to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders version: latest title: ETSI ISG CIM / NGSI-LD API Entry Point Batch Operations API contact: email: NGSI-LD@etsi.org tags: - name: Batch Operations paths: /entityOperations/create: post: description: Batch Entity creation operationId: batchEntityCreation tags: - Batch Operations requestBody: required: true content: application/json;application/ld+json: schema: $ref: '#/components/schemas/EntityList' responses: '200': description: Success content: application/json;application/ld+json: schema: $ref: '#/components/schemas/BatchOperationResult' '400': description: Bad request content: application/json;application/ld+json: schema: $ref: '#/components/schemas/ProblemDetails' /entityOperations/update: post: description: Batch Entity update operationId: batchEntityUpdate tags: - Batch Operations parameters: - name: options in: query required: false schema: type: string enum: - noOverwrite requestBody: required: true content: application/json;application/ld+json: schema: $ref: '#/components/schemas/EntityList' responses: '200': description: Success content: application/json;application/ld+json: schema: $ref: '#/components/schemas/BatchOperationResult' '400': description: Bad request content: application/json;application/ld+json: schema: $ref: '#/components/schemas/ProblemDetails' /entityOperations/upsert: post: description: Batch Entity upsert operationId: batchEntityUpsert tags: - Batch Operations parameters: - name: options in: query required: false schema: type: string enum: - replace - update requestBody: required: true content: application/json;application/ld+json: schema: $ref: '#/components/schemas/EntityList' responses: '200': description: Success content: application/json;application/ld+json: schema: $ref: '#/components/schemas/BatchOperationResult' '400': description: Bad request content: application/json;application/ld+json: schema: $ref: '#/components/schemas/ProblemDetails' /entityOperations/delete: post: description: Batch Entity delete operationId: batchEntityDelete tags: - Batch Operations requestBody: required: true content: application/json;application/ld+json: schema: type: array items: type: string format: uri minItems: 1 responses: '200': description: Success content: application/json;application/ld+json: schema: $ref: '#/components/schemas/BatchOperationResult' '400': description: Bad request content: application/json;application/ld+json: schema: $ref: '#/components/schemas/ProblemDetails' /v2/op/update: post: description: "This operation allows to create, update and/or delete several entities in a single batch operation.\nThe payload is an object with two properties:\n+ `actionType`, to specify the kind of update action to do: either `append`, `appendStrict`, `update`,\n `delete`, or `replace`.\n+ `entities`, an array of entities, each entity specified using the JSON entity representation format\n (described in the section \"JSON Entity Representation\").\nThis operation is split in as many individual operations as entities in the `entities` vector, so\nthe `actionType` is executed for each one of them. Depending on the `actionType`, a mapping with\nregular non-batch operations can be done:\n* `append`: maps to `POST /v2/entities` (if the entity does not already exist) or `POST /v2/entities//attrs`\n (if the entity already exists).\n* `appendStrict`: maps to `POST /v2/entities` (if the entity does not already exist) or\n `POST /v2/entities//attrs?options=append` (if the entity already exists).\n* `update`: maps to `PATCH /v2/entities//attrs`.\n* `delete`: maps to `DELETE /v2/entities//attrs/` on every attribute included in the entity or\n to `DELETE /v2/entities/` if no attribute were included in the entity.\n* `replace`: maps to `PUT /v2/entities//attrs`.\nResponse:\n* Successful operation uses 204 No Content.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." summary: Update tags: - Batch Operations operationId: Update produces: - application/json parameters: - name: Content-Type in: header required: true type: string description: '' - name: body in: body required: true description: '' schema: $ref: '#/definitions/UpdateRequest' - name: options in: query required: false enum: - keyValues x-enum-elements: - name: keyValues description: '' type: string description: Options dictionary responses: '204': description: '' x-unitTests: - request: method: POST uri: /v2/op/update headers: Content-Type: application/json body: '{ "actionType": "append", "entities": [ { "type": "Room", "id": "Bcn-Welt", "temperature": { "value": 21.7 }, "humidity": { "value": 60 } }, { "type": "Room", "id": "Mad_Aud", "temperature": { "value": 22.9 }, "humidity": { "value": 85 } } ]}' expectedResponse: x-allowExtraHeaders: true x-bodyMatchMode: NONE x-arrayOrderedMatching: false x-arrayCheckCount: false x-matchResponseSchema: true headers: {} x-testShouldPass: true x-testEnabled: true x-testName: Update1 x-testDescription: "This operation allows to create, update and/or delete several entities in a single batch operation.\nThe payload is an object with two properties:\n+ `actionType`, to specify the kind of update action to do: either `append`, `appendStrict`, `update`,\n `delete`, or `replace`.\n+ `entities`, an array of entities, each entity specified using the JSON entity representation format\n (described in the section \"JSON Entity Representation\").\nThis operation is split in as many individual operations as entities in the `entities` vector, so\nthe `actionType` is executed for each one of them. Depending on the `actionType`, a mapping with\nregular non-batch operations can be done:\n* `append`: maps to `POST /v2/entities` (if the entity does not already exist) or `POST /v2/entities//attrs`\n (if the entity already exists).\n* `appendStrict`: maps to `POST /v2/entities` (if the entity does not already exist) or\n `POST /v2/entities//attrs?options=append` (if the entity already exists).\n* `update`: maps to `PATCH /v2/entities//attrs`.\n* `delete`: maps to `DELETE /v2/entities//attrs/` on every attribute included in the entity or\n to `DELETE /v2/entities/` if no attribute were included in the entity.\n* `replace`: maps to `PUT /v2/entities//attrs`.\nResponse:\n* Successful operation uses 204 No Content.\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false /v2/op/query: post: description: "The response payload is an Array containing one object per matching entity, or an empty array `[]` if \nno entities are found. The entities follow the JSON entity representation format\n(described in the section \"JSON Entity Representation\").\nThe payload may contain the following elements (all of them optional):\n+ `entities`: a list of entites to search for. Each element is represented by a JSON object with the\n following elements:\n + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same\n time, but one of them must be present.\n + `type` or `typePattern`: Type or type pattern of the entities to search for. Both cannot be used at\n the same time. If omitted, it means \"any entity type\".\n+ `attrs`: List of attributes to be provided (if not specified, all attributes).\n+ `expression`: an expression composed of `q`, `mq`, `georel`, `geometry` and `coords` (see \"List\n entities\" operation above about this field).\n+ `metadata`: a list of metadata names to include in the response.\n See \"Filtering out attributes and metadata\" section for more detail.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." summary: Query tags: - Batch Operations operationId: Query produces: - application/json parameters: - name: Content-Type in: header required: true type: string description: '' - name: body in: body required: true description: '' schema: $ref: '#/definitions/QueryRequest' - name: limit in: query required: false type: number format: double exclusiveMaximum: false exclusiveMinimum: false description: Limit the number of entities to be retrieved. - name: offset in: query required: false type: number format: double exclusiveMaximum: false exclusiveMinimum: false description: Skip a number of records. - name: orderBy in: query required: false type: string description: 'Criteria for ordering results. See "Ordering Results" section for details.' - name: options in: query required: false enum: - count - keyValues - values - unique x-enum-elements: - name: count description: '' - name: keyValues description: '' - name: values description: '' - name: unique description: '' type: string description: Options dictionary responses: '200': description: '' schema: type: array items: $ref: '#/definitions/QueryResponse' examples: application/json: - type: Room id: DC_S1-D41 temperature: value: 35.6 type: Number - type: Room id: Boe-Idearium temperature: value: 22.5 type: Number - type: Car id: P-9873-K temperature: value: 40 type: Number accuracy: 2 timestamp: value: '2015-06-04T07:20:27.378Z' type: DateTime x-unitTests: - request: method: POST uri: /v2/op/query?limit=10&offset=20&orderBy=temperature,!speed headers: Content-Type: application/json body: '{ "entities": [ { "idPattern": ".*", "type": "Room" }, { "id": "Car", "type": "P-9873-K" } ], "attrs": [ "temperature", "humidity" ], "expression": { "q": "temperature>20" }, "metadata": [ "accuracy", "timestamp" ]}' expectedResponse: x-allowExtraHeaders: true x-bodyMatchMode: RAW x-arrayOrderedMatching: false x-arrayCheckCount: false x-matchResponseSchema: true headers: Content-Type: application/json body: '[ { "type": "Room", "id": "DC_S1-D41", "temperature": { "value": 35.6, "type": "Number" } }, { "type": "Room", "id": "Boe-Idearium", "temperature": { "value": 22.5, "type": "Number" } }, { "type": "Car", "id": "P-9873-K", "temperature": { "value": 40, "type": "Number", "accuracy": 2, "timestamp": { "value": "2015-06-04T07:20:27.378Z", "type": "DateTime" } } }]' x-testShouldPass: true x-testEnabled: true x-testName: Query1 x-testDescription: "The response payload is an Array containing one object per matching entity, or an empty array `[]` if \nno entities are found. The entities follow the JSON entity representation format\n(described in the section \"JSON Entity Representation\").\nThe payload may contain the following elements (all of them optional):\n+ `entities`: a list of entites to search for. Each element is represented by a JSON object with the\n following elements:\n + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same\n time, but one of them must be present.\n + `type` or `typePattern`: Type or type pattern of the entities to search for. Both cannot be used at\n the same time. If omitted, it means \"any entity type\".\n+ `attrs`: List of attributes to be provided (if not specified, all attributes).\n+ `expression`: an expression composed of `q`, `mq`, `georel`, `geometry` and `coords` (see \"List\n entities\" operation above about this field).\n+ `metadata`: a list of metadata names to include in the response.\n See \"Filtering out attributes and metadata\" section for more detail.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false /v2/op/notify: post: description: "This operation is intended to consume a notification payload so that all the entity data included by such notification is persisted, overwriting if necessary.\nThis operation is useful when one NGSIv2 endpoint is subscribed to another NGSIv2 endpoint (federation scenarios). \nThe request payload must be an NGSIv2 notification payload. \nThe behaviour must be exactly the same as `POST /v2/op/update` with `actionType` equal to `append`.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." summary: Notify tags: - Batch Operations operationId: Notify produces: - application/json parameters: - name: Content-Type in: header required: true type: string description: '' - name: body in: body required: true description: '' schema: $ref: '#/definitions/NotifyRequest' - name: options in: query required: false enum: - keyValues x-enum-elements: - name: keyValues description: '' type: string description: Options dictionary responses: '200': description: '' x-unitTests: - request: method: POST uri: /v2/op/notify headers: Content-Type: application/json body: '{ "subscriptionId": "5aeb0ee97d4ef10a12a0262f", "data": [{ "type": "Room", "id": "DC_S1-D41", "temperature": { "value": 35.6, "type": "Number" } }, { "type": "Room", "id": "Boe-Idearium", "temperature": { "value": 22.5, "type": "Number" } }]}' expectedResponse: x-allowExtraHeaders: true x-bodyMatchMode: NONE x-arrayOrderedMatching: false x-arrayCheckCount: false x-matchResponseSchema: true headers: Content-Type: application/json x-testShouldPass: true x-testEnabled: true x-testName: Notify1 x-testDescription: "This operation is intended to consume a notification payload so that all the entity data included by such notification is persisted, overwriting if necessary.\nThis operation is useful when one NGSIv2 endpoint is subscribed to another NGSIv2 endpoint (federation scenarios). \nThe request payload must be an NGSIv2 notification payload. \nThe behaviour must be exactly the same as `POST /v2/op/update` with `actionType` equal to `append`.\nResponse code:\n* Successful operation uses 200 OK\n* Errors use a non-2xx and (optionally) an error payload. See subsection on \"Error Responses\" for\n more details." x-operation-settings: CollectParameters: false AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false components: schemas: Entity: allOf: - required: - id - type - $ref: '#/components/schemas/EntityFragment' positionArray: description: An array of positions type: array items: $ref: '#/components/schemas/position' LineString: type: object properties: type: type: string enum: - LineString coordinates: $ref: '#/components/schemas/lineString' MultiLineString: type: object properties: type: type: string enum: - MultiLineString coordinates: type: array items: $ref: '#/components/schemas/lineString' Point: type: object properties: type: type: string enum: - Point coordinates: $ref: '#/components/schemas/position' Name: type: string pattern: ^((\d|[a-zA-Z]|_)+(:(\d|[a-zA-Z]|_)+)?(#\d+)?)$ minLength: 1 description: NGSI-LD Name Relationship: type: object properties: type: type: string enum: - Relationship object: type: string format: uri observedAt: $ref: '#/components/schemas/observedAt' createdAt: $ref: '#/components/schemas/createdAt' modifiedAt: $ref: '#/components/schemas/modifiedAt' datasetId: $ref: '#/components/schemas/datasetId' instanceId: $ref: '#/components/schemas/instanceId' required: - type - object additionalProperties: oneOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Relationship' BatchOperationResult: type: object properties: success: type: array items: type: string format: uri error: type: array items: $ref: '#/components/schemas/BatchEntityError' Property: type: object properties: type: type: string enum: - Property value: oneOf: - string - number - boolean - array - object observedAt: $ref: '#/components/schemas/observedAt' createdAt: $ref: '#/components/schemas/createdAt' modifiedAt: $ref: '#/components/schemas/modifiedAt' datasetId: $ref: '#/components/schemas/datasetId' instanceId: $ref: '#/components/schemas/instanceId' required: - type - value additionalProperties: oneOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Relationship' modifiedAt: type: string format: date-time Polygon: type: object properties: type: type: string enum: - Polygon coordinates: $ref: '#/components/schemas/polygon' EntityFragment: type: object properties: '@context': $ref: '#/components/schemas/LdContext' location: $ref: '#/components/schemas/GeoProperty' observationSpace: $ref: '#/components/schemas/GeoProperty' operationSpace: $ref: '#/components/schemas/GeoProperty' id: type: string format: uri type: $ref: '#/components/schemas/Name' createdAt: $ref: '#/components/schemas/createdAt' modifiedAt: $ref: '#/components/schemas/modifiedAt' additionalProperties: oneOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Relationship' - $ref: '#/components/schemas/GeoProperty' position: description: A single position type: array minItems: 2 maxItems: 2 items: type: number additionalProperties: false BatchEntityError: type: object properties: entityId: type: string format: uri error: $ref: '#/components/schemas/ProblemDetails' ProblemDetails: type: object properties: type: type: string format: uri title: type: string detail: type: string required: - type linearRing: description: An array of four positions where the first equals the last allOf: - $ref: '#/components/schemas/positionArray' - minItems: 4 MultiPoint: type: object properties: type: type: string enum: - MultiPoint coordinates: $ref: '#/components/schemas/positionArray' datasetId: type: string format: uri lineString: description: An array of two or more positions allOf: - $ref: '#/components/schemas/positionArray' - minItems: 2 EntityList: type: array items: $ref: '#/components/schemas/Entity' polygon: description: An array of linear rings type: array items: $ref: '#/components/schemas/linearRing' GeoProperty: type: object properties: type: type: string enum: - GeoProperty value: $ref: '#/components/schemas/Geometry' observedAt: $ref: '#/components/schemas/observedAt' createdAt: $ref: '#/components/schemas/createdAt' modifiedAt: $ref: '#/components/schemas/modifiedAt' datasetId: $ref: '#/components/schemas/datasetId' instanceId: $ref: '#/components/schemas/instanceId' required: - type - value additionalProperties: oneOf: - $ref: '#/components/schemas/Property' - $ref: '#/components/schemas/Relationship' instanceId: type: string format: uri observedAt: type: string format: date-time MultiPolygon: type: object properties: type: type: string enum: - MultiPolygon coordinates: type: array items: $ref: '#/components/schemas/polygon' LdContext: oneOf: - type: object - type: string format: uri - type: array minItems: 1 items: oneOf: - type: string format: uri - type: object Geometry: description: ' Avalid GeoJSON geometry object' oneOf: - $ref: '#/components/schemas/Point' - $ref: '#/components/schemas/MultiPoint' - $ref: '#/components/schemas/Polygon' - $ref: '#/components/schemas/LineString' - $ref: '#/components/schemas/MultiLineString' - $ref: '#/components/schemas/MultiPolygon' createdAt: type: string format: date-time definitions: NotifyRequest: title: Notify request example: subscriptionId: 5aeb0ee97d4ef10a12a0262f data: - type: Room id: DC_S1-D41 temperature: value: 35.6 type: Number - type: Room id: Boe-Idearium temperature: value: 22.5 type: Number type: object properties: subscriptionId: description: '' example: 5aeb0ee97d4ef10a12a0262f type: string data: description: '' example: - type: Room id: DC_S1-D41 temperature: value: 35.6 type: Number - type: Room id: Boe-Idearium temperature: value: 22.5 type: Number type: array items: type: object required: - subscriptionId - data QueryRequest: title: Query request example: entities: - idPattern: .* type: Room - id: Car type: P-9873-K attrs: - temperature - humidity expression: q: temperature>20 metadata: - accuracy - timestamp type: object properties: entities: description: '' example: - idPattern: .* type: Room - id: Car type: P-9873-K type: array items: type: object attrs: description: '' example: - temperature - humidity type: array items: type: string expression: description: '' example: q: temperature>20 type: object metadata: description: '' example: - accuracy - timestamp type: array items: type: string required: - entities - attrs - expression - metadata QueryResponse: title: Query response example: type: Room id: DC_S1-D41 temperature: value: 35.6 type: Number type: object properties: type: description: '' example: Room type: string id: description: '' example: DC_S1-D41 type: string temperature: description: '' example: value: 35.6 type: Number type: object required: - type - id - temperature UpdateRequest: title: Update request example: actionType: append entities: - type: Room id: Bcn-Welt temperature: value: 21.7 humidity: value: 60 - type: Room id: Mad_Aud temperature: value: 22.9 humidity: value: 85 type: object properties: actionType: description: '' example: append type: string entities: description: '' example: - type: Room id: Bcn-Welt temperature: value: 21.7 humidity: value: 60 - type: Room id: Mad_Aud temperature: value: 22.9 humidity: value: 85 type: array items: type: object required: - actionType - entities externalDocs: description: Find out more about the ETSI ISG Context Information Management url: https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854