diff --git a/md/clause-7.md b/md/clause-7.md index 4700ccfa9d182c94c906528fc0a1fdad9b244dad..ba337f485083b54dfefb0fafba7f9837699ab869 100644 --- a/md/clause-7.md +++ b/md/clause-7.md @@ -998,7 +998,7 @@ Table: Update Attributes request body and possible responses | +---------------------------------------------+-------------+---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | N/A | N/A | 204 No content | All the Attributes were updated successfully. | | +---------------------------------------------+-------------+---------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | UpdateResult | 1 | 207 Multi-Status | Only the Attributes included in the response payload body were successfully updated. If no Attributes were successfully updated the _`updated`_ array of _UpdateResult_ (see [n.1] ~clause 5.2.6.8.5) | +| | UpdateResult | 1 | 207 Multi-Status | Only the Attributes included in the response payload body were successfully updated. If no Attributes were successfully updated the _`updated`_ array of _UpdateResult_ (see [n.1] ~clause 5.2.6.8.5) | | | | | | will be empty. | | | | | | | | | | | | If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. | @@ -1054,6 +1054,120 @@ Table: URI variables #### 7.5.3.1 GET/HEAD +This method is associated to the operation "Retrieve Attribute Value" and shall +exhibit the behaviour defined by [n.1] ~clause 10.4.4, providing a Value +Fragment as part of the HTTP response payload body. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Attribute Value interaction +::: + + + + + +The URL parameters that shall be supported by implementations are those defined +in Table+++below, the request headers that shall be supported by implementations +are those defined in Table+++below+++below and Table+++below+++below+++below +describes the request body and possible responses. + + + +::: TH +Table: Retrieve Attribute Value URL parameters +::: + +::: TAL ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | | ++===================+===========================================+=================+===========================================================================================================================================================================================================================================================================================================================================+ +| datasetId | String | 0..1 | Shall be a valid URI, ["@none"]{.HTML-Code} for return the default Attribute instance. Specifies the datasetId of the Attribute instance to be selected for the Attribute as per [n.1] ~clause 8.5. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| entityMap | Boolean | 0..1 | If _`true`_, the location of the EntityMap used in the operation is returned in the response. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| entityMapLifetime | String | 0..1 | Suggested duration, represented in ISO 8601 [n.21] format [n.21], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if _`entityMap`_ is set to _`true`_. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| join | String | 0..1 | The type of [Linked Entity]{.HTML-Keyboard} retrieval to apply (see [n.1] ~clause 7.7). Allowed values: ["inline","@none"]{.HTML-Code}. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| joinLevel | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML-Keyboard} retrieval to apply. | +| | | | | +| | | | Only applicable if _`join`_ parameter is present. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lang | String | 0..1 | It represents the preferred natural language of the response. | +| | | | | +| | | | It is used to reduce a _`languageMap`_ to a string or string array property in a single preferred language. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | +| | | | | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Retrieve Attribute Value Headers +::: + +::: TAL ++------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++==================+=================+=================+=============================================================================================================================================================================================================+ +| NGSILD-EntityMap | URI | 0..1 | If present, the EntityMap supplied is used for determining the Entity requested. The location of the EntityMap used in the query operation is returned in the response. | ++------------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + + +::: TH +Table: Retrieve Attribute Value request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| Request Body | Data Type | Cardinality | Remarks | +| +---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | {TAL} | {TAL} | | +| | | | | +| | N/A | N/A | | ++---------------+---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | | +| Response Body | Data Type | Cardinality | Response Codes | Remarks | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | Value Fragment | 1 | 200 OK | A response body containing the JSON-LD representation of the target Attribute. | +| | | | | | +| | | | | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML-Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | Value Fragment | 1 | 203 Non-Authoritative Information | As above, but returning an **altered response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [n.1] ~clause 9.5.3. | +| | | | | | +| | | | | The response shall also include a ["Preference-Applied"]{.HTML-Code} HTTP header set to ["ngsi-ld="]{.HTML-Code}. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | 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. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) or Attribute name is not known to the system, see clause 6.3.2. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 501 Not Implemented | It is used by Registered [Context Sources]{.HTML-Keyboard} to indicate that the data format of the request is unsupported, see clause 6.4.2. | ++---------------+---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + #### 7.5.3.2 PATCH This method is bound to the "Partial Attribute Update" operation and shall @@ -1301,8 +1415,174 @@ This resources represents the value of an attribute of a Entity. #### 7.6.3.1 GET/HEAD +This method is associated to the operation "Retrieve Attribute Value" and shall +exhibit the behaviour defined by [n.1] ~clause 10.4.4, providing a **value +only** Value Fragment as part of the HTTP response payload body. + + + +::: FL + +::: + +::: TF +Figure: Retrieve Attribute Value interaction +::: + + + +The URL parameters that shall be supported by implementations are those defined +in Table+++below, the request headers that shall be supported by implementations +are those defined in Table+++below+++below and Table+++below+++below+++below +describes the request body and possible responses. + + + +::: TH +Table: Retrieve Attribute Value URL parameters +::: + +::: TAL ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | | ++===================+===========================================+=================+===========================================================================================================================================================================================================================================================================================================================================+ +| datasetId | String | 0..1 | Shall be a valid URI, ["@none"]{.HTML-Code} for return the default Attribute instance. Specifies the datasetId of the Attribute instance to be selected for the Attribute as per [n.1] ~clause 8.5. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| entityMap | Boolean | 0..1 | If _`true`_, the location of the EntityMap used in the operation is returned in the response. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| entityMapLifetime | String | 0..1 | Suggested duration, represented in ISO 8601 [n.21] format [n.21], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if _`entityMap`_ is set to _`true`_. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lang | String | 0..1 | It represents the preferred natural language of the response. | +| | | | | +| | | | It is used to reduce a _`languageMap`_ to a string or string array property in a single preferred language. | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | +| | | | | ++-------------------+-------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + + +::: TH +Table: Retrieve Attribute Value request body and possible responses +::: + + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| Request Body | Data Type | Cardinality | Remarks | +| +---------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | {TAL} | {TAL} | | +| | | | | +| | N/A | N/A | | ++---------------+---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | | +| Response Body | Data Type | Cardinality | Response Codes | Remarks | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | **value only** Value Fragment | 1 | 200 OK | A response body (JSON Primitive, Object or Array) containing the value from the target Attribute. | +| | | | | | +| | | | | If an EntityMap has been requested, the HTTP response shall include an ["NGSILD-EntityMap"]{.HTML-Code} HTTP header that contains the resource URI of the EntityMap resource used in the operation. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | **value ionly** Value Fragment | 1 | 203 Non-Authoritative Information | As above, but returning an **altered response body,** amended to conform to a specific version of the NGSI-LD specification as mandated in [n.1] ~clause 9.5.3. | +| | | | | | +| | | | | The response shall also include a ["Preference-Applied"]{.HTML-Code} HTTP header set to ["ngsi-ld="]{.HTML-Code}. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | 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. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier (URI) or Attribute name is not known to the system, see clause 6.3.2. | +| +---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 501 Not Implemented | It is used by Registered [Context Sources]{.HTML-Keyboard} to indicate that the data format of the request is unsupported, see clause 6.4.2. | ++---------------+---------------------------------------------+-------------+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + #### 7.6.3.2 PUT +This method is associated to the operation "Set Attribute Value" and shall +exhibit the behaviour defined by [n.1] ~clause 10.2.6, using a **value only** +Value Fragment as the HTTP payload request body. + + + +::: FL + +::: + +::: TF +Figure: Set Attribute Value interaction +::: + + + + + +::: TH +Table: Set Attribute Value URL parameters +::: + +::: TAL ++-----------------+---------------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================================+=================+==========================================================================================================================================================================================================================================================================================+ +| datasetId | String | 0..1 | Shall be a valid URI, ["@none"]{.HTML-Code} for return the default Attribute instance. Specifies the datasetId of the Attribute instance to be selected for the Attribute as per [n.1] ~clause 8.5. | ++-----------------+---------------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| observedAt | String | 0..1 | It shall be a _DateTime_ (see [n.1] ~clause 5.2.2.4). | +| | | | | +| | | | When a Set Attribute Value operation applies to a pre-existing Attribute which previously contained an _`observedAt`_ sub-attribute, the value held in this query parameter shall be used in preference to the server time. | ++-----------------+---------------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| type | String | 0..1 | Selection of Entity Types as per [n.1] ~clause 7.2.2. | ++-----------------+---------------------------------+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + + + +::: TH +Table: Set Attribute Value request body and possible responses +::: + +::: {.TAL .no-table-stripes} ++---------------+---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | +| Request Body | Data Type | Cardinality | Remarks | +| +---------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | {TAL} | {TAL} | {TAL} | +| | | | | +| | **value only** Value Fragment | 1 | JSON Primitive, Object or Array containing the value to set within the target Attribute. | ++---------------+---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| {TAH} | {TAH} | {TAH} | {TAH} | {TAH} | +| | | | | | +| Response Body | Data Type | Cardinality | Response Codes | Remarks | +| +---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | N/A | N/A | 204 No content | The Attribute value was updated successfully. | +| +---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | BatchOperationResult | 1 | 207 Multi-Status | 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.5. | +| +---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 400 Bad Request | 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. | +| +---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| | ProblemDetails (see IETF RFC 7807 [n.24]) | 1 | 404 Not Found | It is used when a client provided an Entity identifier or Attribuet name is not known to the system, see clause 6.3.2. | ++---------------+---------------------------------------------+-------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + ## 7.7 Resource: entityOperations/create ### 7.7.1 Description