6.6 Extensibility Mechanisms

29.5003GPP5G SystemRelease 17Stage 3Technical Realization of Service Based ArchitectureTS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

6.6.1 General

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

6.6.2 Feature negotiation

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 optional 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 optional 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 3GPP TS 29.571 [13] 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 3GPP TS 29.571 [13] 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 optional 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 3GPP TS 29.571 [13] 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 3GPP TS 29.571 [13] in HTTP GET requests to fetch resource(s) associated to the NF Service Consumer of 5G API. This query parameter indicates which of the optional 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 3GPP TS 29.571 [13] 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 3GPP TS 29.501 [5]), 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.

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.

NOTE: The sender may send such information before the supported features for a resource have been determined.

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 3GPP TS 29.571 [13] 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 3GPP TS 29.571 [13], 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 3GPP TS 29.571 [13] 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 3GPP TS 29.571 [13], 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.

6.6.3 Vendor-specific extensions

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

NOTE 1: The only JSON data types that can be extended, by defining additional members, are JSON objects; simple data types (and arrays of items of simple data types) cannot be extended in this way.

However, in order to avoid duplication of member names inside a same object (see 3GPP TS 29.501 [5], clause 5.2.4.2, 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:

"vendorSpecific-nnnnnn": {

…

}

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.

NOTE 2: The content (value) of those vendor-specific member elements, and their usage, is not to be defined by any of the 3GPP Technical Specifications. Also, the type of value assigned to these members is not defined by 3GPP, and therefore, they can be any of the types allowed in the JSON specification: objects, arrays, or simple types (string, number, Boolean, etc.). However, to allow future extensibility of these values, it is recommended that they are defined as objects.

EXAMPLE: The vendor-specific member name for vendor "3GPP" would be:

"vendorSpecific-010415": {

…

}

6.6.4 Extensibility for Query parameters

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.

NOTE 1: Not doing so could result in the NF Service Producer rejecting the request if it does not support the query parameters, see clause 5.2.9.

NOTE 2: A NF Service Consumer can discover the features (and therefore the query parameters) supported by a NF Service Producer using the NRF, if the latter has registered the features it supports to the NRF.

If the NF Service Consumer includes the query parameter (e.g. "supported-features") of the SupportedFeatures data type defined in 3GPP TS 29.571 [13] 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 3GPP TS 29.571 [13] in the HTTP GET response, set as defined for HTTP responses in clause 6.6.2, if supported by the API definition.

NOTE 3: This allows a NF Service Consumer to discover the features (and therefore the query parameters) supported by the NF Service Producer when the first interaction with the NF Service Producer is an HTTP GET request and the service was not discovered via the NRF, e.g. for a NF Discovery Request sent to the NRF.

NOTE 4: Some APIs are designed to allow returning the attribute of the SupportedFeatures data type defined in 3GPP TS 29.571 [13] in the HTTP GET response, regardless of whether the query parameter of the SupportedFeatures data type defined in 3GPP TS 29.571 [13] is present in the request.

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 3GPP TS 29.571 [13] 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.