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: 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:

• 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.

In these scenarios, it is critical that any JSON Pointer expression is applied by both client and server on the exact same array representation, since otherwise the indexes may vary, and the JSON Pointer will give unexpected results. A typical scenario that may create issues could be as follows: Another scenario that may lead to incorrect array updates is: 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.