Content for  TS 29.500  Word version:  19.0.0

This clause describes the extensibility mechanisms supported in the Service-Based Architecture in 3GPP 5GC, such as feature negotiation, vendor-specific extensions, etc.

A versioning of services in the request URI shall be supported by 3GPP 5G APIs, but version upgrades shall only be applied for non-backward compatible changes or the introduction of new mandatory features. The following mechanism to negotiate applicable features shall be used by 5G APIs. This supported feature mechanism shall be applied separately for each API. For any API that defines resources, suitable resources associated to or representing the NF Service Consumer (e.g. a top-level resource or a sub-resource representing the NF Service Consumer) shall be identified in each API to support the negotiation of the applicable features between the NF Service Consumer and NF Service Producer for this resource. Each such resource for a 5G API shall contain an attribute (e.g. "supportedFeatures") of the SupportedFeatures data type defined in TS 29.571 containing a bitmask to indicate supported features. The features and their positions in that bitmask are defined separately for each API. The HTTP client acting as NF service consumer shall include the attribute of the SupportedFeatures data type defined in TS 29.571 in the HTTP PUT or POST requests to create the resource associated to or representing the NF Service Consumer of 5G API. This attribute indicates which of the features defined for the corresponding service are supported by the HTTP client. The HTTP server shall determine the supported features for the corresponding resource by comparing the supported features indicated by the client with the supported features the HTTP server supports. Features that are supported both by the client and the server are supported for that resource. The HTTP server shall include the attribute of the SupportedFeatures data type defined in TS 29.571 indicating those features in the representation of the resource it returns to the HTTP client in the HTTP response confirming the creation of the resource. The HTTP client acting as NF service consumer may include a query parameter (e.g. "supported-features") of the SupportedFeatures data type defined in TS 29.571 in HTTP GET requests to fetch resource(s) associated to the NF Service Consumer of 5G API. This query parameter indicates which of the features defined for the corresponding service are supported by the HTTP client. The HTTP server shall determine the supported features for the corresponding resource(s) by comparing the supported features indicated by the client with the supported features the HTTP server supports. Features that are supported both by the client and the server are supported for the resource(s); attributes or enumerated values that are only of relevance to a feature unsupported by the requested resource(s) should be omitted from the representation sent in the response. The HTTP Server shall include the attribute of the SupportedFeatures data type defined in TS 29.571 indicating those features in the HTTP GET response, if supported by the API definition. The supported features for a resource associated to or representing the NF Service Consumer shall also be applicable to all subordinate resources of that resource, and for all custom operations related to any of those resources. If any of those resources is used for the subscription to notifications (see clause 4.6.2 of TS 29.501), the supported features shall also apply to those notifications. For default notification subscriptions, the supported features shall be determined by comparing the supported features if registered by the NF Service Consumer for the corresponding default notification subscription in NRF with the features supported by the NF Service Producer. Features that are supported by both are supported for the default notification subscription, which shall also apply to related default notifications. When an NF service consumer subscribes to notifications from an NF service producer via an intermediate NF (see Figure 7.1.2-3 of TS 23.501), the NF service consumer may indicate, to the intermediate NF and the NF service producer, the API version(s) and the features it supports for the corresponding NF service producer's service by including the 3gpp-Sbi-Consumer-Info header in its request as described in clauses 5.2.3.3.7 and 6.2.2. When required by a given API, the NF service producer may then indicate the features supported by both the NF service consumer and NF service producer for the subscription and its notifications by including an attribute of the SupportedFeatures data type in the notification request it sends towards the NF service consumer. Attributes used for the representation of a resource, particular values in enumerated data types, and/or procedural description can be marked to relate to a particular supported feature. Such attributes shall not be mandated in data structures. Such attributes or enumerated values shall only be sent and such procedures shall only be applied if the corresponding feature is supported. Unknown attributes and values shall be ignored by the receiving entity. Unsupported query parameters shall be handled as specified in clause 5.2.9. For an API that does not define any resources, only custom operations without associated resources or notifications without subscription will be used. For such APIs, if a feature negotiation is desired, the request and response bodies of a suitable custom operation or notification need to be defined in such a manner that an attribute of the SupportedFeatures data type defined in TS 29.571 is included. The client invoking that custom operation or notification shall indicate its supported features for that API within the corresponding HTTP request. The data structures to be included in the HTTP request as defined for that API, shall include the attribute of the SupportedFeatures data type defined in TS 29.571, preferably in the outermost data structure for cases where the body contains a complex structure with several layers of JSON objects. The server shall determine the supported features by comparing the supported features indicated by the client with its own supported features. Features that are supported both by the client and the server are supported for subsequent custom operations and notifications of that API. The server shall include the attribute of the SupportedFeatures data type defined in TS 29.571 indicating those features in the successful response to the custom operation or notification. The data structures to be included in the HTTP response as defined for that API, shall include the attribute of the SupportedFeatures data type defined in TS 29.571, preferably in the outermost data structure for cases where the body contains a complex structure with several layers of JSON objects. The client and server shall only use those supported features in subsequent communication of that API between each other until the supported feature negotiation performed as part of that communication yields a new result. Additionally, a NF instance should register all the features it supports to the NRF, to enable NF Service Consumers to discover NF Service Producers supporting specific features. A NF instance should register all the features it supports as NF Service Consumer in the corresponding default notification subscription in its NF profile to the NRF, to enable NF Service Producer to select NF Service Consumer supporting specific features. Specific requirements for support of Indirect Communication with Delegated Discovery are specified in clause 6.10.6.

Information elements sent on the 3GPP 5GC APIs should be extensible with vendor-specific data. The definition of JSON data structures using OpenAPI as Interface Definition Language (see OpenAPI Specification [9]) allows to extend by default any JSON object with additional member elements, as long as no specific directives are included in the schema definition preventing such extension (e.g., by setting "additionalProperties" to false). However, in order to avoid duplication of member names inside a same object (see clause 5.2.4.2 of TS 29.501, for the requirement of uniqueness of member names in JSON objects), it is necessary to comply with a naming scheme for vendor-specific data elements, to avoid clashing names between vendors. Vendor-specific member names in JSON objects shall be named in the following manner: where the value "nnnnnn" is a fixed 6-digit string, using the IANA-assigned "SMI Network Management Private Enterprise Codes" [18] value associated to a given vendor, and padding with leading digits "0" to complete a 6-digit value. EXAMPLE: The vendor-specific member name for vendor "3GPP" would be:

New query parameters may be defined after the OpenAPI freeze of the first 3GPP release that contains an API. A new feature should be defined in the API for any query parameter added in a new version of the API or for any new functionality resulting in defining new query parameter(s). A single feature may be defined, if appropriate, when adding multiple query parameters in a new version of the API. Prior to using such a query parameter in an HTTP request, the NF Service Consumer should determine, if possible, whether the query parameter is supported by the NF Service Producer, using the feature negotiation mechanism specified in clause 6.6.2. If the NF Service Consumer includes the query parameter (e.g. "supported-features") of the SupportedFeatures data type defined in TS 29.571 in an HTTP GET request (see clause 6.6.2), the NF Service Producer shall include the attribute (e.g. "supportedFeatures") of the SupportedFeatures data type defined in TS 29.571 in the HTTP GET response, set as defined for HTTP responses in clause 6.6.2, if supported by the API definition. If a NF Service Consumer uses such a query parameter in an HTTP GET request without prior knowledge of whether it is supported by the NF Service Producer, the NF Service Consumer shall be prepared to receive a successful response that may not match all the query parameters sent in the request, and to act accordingly. The NF Service Consumer may use the attribute of the SupportedFeatures data type defined in TS 29.571 returned by the NF Service Producer in the HTTP GET response, if available, to determine the features (and thus query parameters) not supported by the NF Service Producer. When defining new query parameters in a new version of an API, it needs to be checked that the addition of the query parameter does not cause backward compatibility problems with NF Service Producers complying with an earlier version of the API, e.g. if the query parameter is ignored in a HTTP GET request. Otherwise, it needs to be ascertained that the NF Service Consumer does not use such a query parameter without prior knowledge that it is supported by the NF Service Producer.