Content for TS 29.501 Word version: 19.0.0
E Considerations for handling of JSON arrays |R16| p. 80
This Annex provides guidelines on the use of JSON arrays on the SBI APIs of the 5GC.
As described in clause 5.2.4, the data model of an API definition in a 5GC API consists of any of the different data types supported by OpenAPI, corresponding to the different data structures found in the JSON data format. One of these structures is the "array", representing a set of ordered values.
It should be noted that, while JSON allows that the value of the elements of an array may be of different types, in OpenAPI Specification [4] this is further restricted, and all elements of an array shall be of the same type.
Also, it is important to note that the JSON format itself, as specified in RFC 8259, does not define any syntax to refer to specific array elements.
However, there are certain conventions to specify mechanism to refer to array elements, e.g. based on the position a given element has in the array.
In particular, the JSON Pointer syntax defines a string syntax for identifying a specific value within a JSON document. This syntax consists of a number of tokens separated by the "/" character; in order to refer to a specific element in an array, then token shall contain an unsigned decimal value, indicating the zero-based index of the element in the array.
EXAMPLE:
JSON document:
There are several scenarios, frequently employed in the 5GC APIs, that make use of the JSON Pointer mechanism to refer to specific elements in an array:
{
"attr1": 0,
"attr2": true,
"attr3": [ 1, 2, 3 ]
}
JSON Pointer expression "/attr3/0" evaluated on such JSON document: 1
- Update of resources using the PATCH method, as described in clause 4.6.1.1.3.2. If the syntax used in the PATCH request payload is based on the "JSON Patch" format, then the JSON Pointer mechanism is used to specify patch operations applied to specific array elements.
- Notifications of events (such as data changes), as described in clause 4.6.2.3, using as notification payload the notation defined in "NotifyItem" / "ChangeItem" data types defined in TS 29.571. This notation is similar to "JSON Patch", so it also makes use of the JSON Pointer syntax to refer to specific array elements.
- Explicit usage of attributes containing JSON Pointer expressions in request or response payloads.
1.
Another scenario that may lead to incorrect array updates is:
NF Service Consumer sends a first GET request towards a NF Service Producer, including certain query parameters in the HTTP request, that result into retrieving a resource representation that contains a subset of the data that the NF Service Producer holds under such resource. When such subset refers to returning just some of the elements of an array, rather than the entire array, then the content of the array will differ between consumer and producer.
2a.
The NF Service Consumer sends a subsequent PATCH request towards the NF Service Producer, with the intention to modify a given element of the array (specified by the array index, per the JSON Pointer syntax). This results into the server modifying a wrong element in the array, given that the NF Service Producer contains a different array.
2b.
The NF Service Consumer may subscribe to be notified by the NF Service Producer when a given resource representation has changed. When the NF Service Producer detects such a change, it sends a notification that may include a reference to an array index, which may be different than the array index kept by the NF Service Producer.
2c.
The NF Service Consumer is a stateless NF Service Consumer that has no local representation of the array that subscribes to be notified by the NF Service Producer when a given resource representation has changed.
1.
The design of 5GC SBI APIs should take into account these scenarios and provide mechanisms to avoid unintended modifications of array elements, when they are referred by their position index in the array.
To achieve these, both NF Service Consumer and Producer (taking the role of HTTP client and server) should ensure that any resource update takes place on a known and current resource representation, based on the content of ETag values sent along with resource representations by the resource owner.
If an NF Service Consumer needs to cache a resource representation received from an NF Service Producer (i.e. the JSON information received in an HTTP response message), it shall use the exact same representation of arrays as received from the service producer.
When sending notifications or modifications whose semantics is based on the JSON Pointer syntax, the sending NF shall use the exact same representation of arrays as previously signalled in a previous interaction with the receiver of such notifications/modifications.Further, when sending notifications whose semantics is based on the JSON Pointer syntax, if the NF Service Consumer is a stateless NF Service Consumer and thus has no local representation of the array, the NF Producer shall use the complete replacement array representation as the NF Service Consumer is otherwise required to request the complete data from the NF Service Producer with a GET request.
Two different NF Service Consumer sends a GET request towards a NF Service Producer to retrieve the representation of a certain resource.
2.
A first NF Service Consumer NF1 sends a PATCH request towards the NF Service Producer, with the intention to delete a given element of the array (specified by the array index, per the JSON Pointer syntax). This results in some of the array indexes being changed (of those elements placed after the deleted element)
3.
A second NF Service Consumer NF2, sends another PATCH request towards the NF Service Producer, to modify any of the elements of the array whose index was affected by the previous operation done by NF1. This results in modifying unintendedly the wrong array element.
