5 Documenting 5GC SBI APIs

29.5013GPP5G SystemPrinciples and Guidelines for Services DefinitionRelease 18Stage 3TS

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

5.1 Naming Conventions

5.1.1 Case Conventions

The following case conventions for names and strings are used in the 5GC SBI service APIs.

1) UPPER_WITH_UNDERSCORE

All letters of a string are capital letters. Digits are allowed. Word boundaries are represented by the underscore "_" character. No other characters are allowed.

Example 1:

a) DATA_MANAGEMENT

b) CELL_CHANGE

2) lower_with_underscore

All letters of a string are lowercase letters. Digits are allowed. Word boundaries are represented by the underscore "_" character. No other characters are allowed.

Example 2:

a) data_management;

b) cell_change.

3) UPPER-WITH-HYPHEN

All letters of a string are capital letters. Digits are allowed. Word boundaries are represented by the hyphen "-" character. No other characters are allowed.

Example 3:

a) DATA-MANAGEMENT

b) CELL-CHANGE

4) lower-with-hyphen

All letters of a string are lowercase letters. Digits are allowed. Word boundaries are represented by the hyphen "-" character. No other characters are allowed.

Example 4:

a) data-management;

b) cell-change.

5) UpperCamel

A string is formed by concatenating words. Each word starts with a letter or a digit. The first letter of each word shall be an uppercase letter; all other characters in the word shall be lowercase letters or digits.

Abbreviations follow the same scheme (i.e. first letter uppercase, all other letters lowercase).

Example 5:

a) DataManagement.

b) CellChange

c) 5QiPriorityLevel

d) Amf3GppAccessRegistration

6) lowerCamel

A string is formed by concatenating words.Each word starts with a letter or a digit. The first letter of the first word shall be a lowercase letter; the first letter of the rest of the words shall be an uppercase letter. All other characters in the words shall be lowercase letters or digits.

Abbreviations follow the same scheme.

Example 6:

a) dataManagement

b) cellChange

c) 5qiPriorityLevel

NOTE: These naming conventions are used as guidelines, to provide some uniformity in the specification of the different 5GC APIs. However, for different reasons, sometimes exceptions can be made. In any case, the OpenAPI specifications are mandatory, and the different network elements cannot determine that a certain message, that otherwise complies to the OpenAPI specification, is incorrect based only on the fact that it does not follow a given naming convention in a certain data element.

5.1.2 API Naming Conventions

An API shall take the name of the corresponding service (e.g. Nudm_SubscriberDataManagement). When used in URIs the name shall be converted to lower-with-hyphen and may use an abbreviated form (e.g. nudm-sdm).

5.1.3 Conventions for URI Parts

5.1.3.1 Introduction

The parts of the URI syntax that are relevant in the context of the 5GC SBI service APIs are as follows:

– Path, consisting of segments, separated by "/" (e.g. segment1/segment2/segment3).

– Query, consisting of pairs of parameter name and value (e.g., ?mcc=262&mnc=01, where two pairs are presented).

5.1.3.2 URI Path Segment Naming Conventions

a) All path segments of a resource URI which represent a string constant shall use lower-with-hyphen (this implies that a path cannot end with "/").

Example 1:

subscriber-data

b) If a resource represents a collection of entities and the last path segment of the resource URI is a string constant, that last path segment shall be plural.

Example 2:

…/prefix/api/v1/users

c) For resources where the last path segment of the resource URI is a string constant, that last path segment shall be a noun or a composite noun.

Example 3:

…/prefix/api/v1/users

Example 4:

…/prefix/api/v1/user-session

d) For custom operations, the last path segment of the URI via which the operation is invoked shall be a verb, or shall start with a verb.

Example 5:

…/app_instances/{appInstanceId}/instantiate

Example 6:

…/sessions/terminate-all

e) All path segments of a URI which are variable names shall use lowerCamel, and shall be surrounded by curly brackets.

Example 7:

…/subscriber-data/{supi}

f) Once a variable is replaced at runtime by an actual string, the string shall follow the rules for a path segment defined in IETF RFC 3986 [9]. IETF RFC 3986 [9] disallows certain characters from use in a path segment. Each actual 5GC SBI service API specification shall define this restriction to be followed when generating values for path segment variables, or propose a suitable encoding (such as percent-encoding according to IETF RFC 3986 [9]), to escape such characters if they can appear in input strings intended to be substituted for a path segment variable.

5.1.3.3 URI Query Naming Conventions

a) URI query parameter names in queries shall use lower-with-hyphen.

Example 1:

?nf-type=AMF

b) Variables that represent actual parameter values in queries shall use lowerCamel and shall be surrounded by curly brackets.

Example 2:

?nf-id={chooseAValue}

c) When a variable is replaced at runtime by an actual string, the convention defined in clause 5.1.3.2 item f) applies to that string.

5.1.4 Conventions for Names in Data Structures

The following syntax conventions apply when defining the names for attributes in the 5GC SBI service API data structures, carried in the payload body of http requests and responses.

a) Names of attributes shall be represented using lowerCamel.

Example 1:

attributeName

b) Names of arrays (i.e. those with cardinality 1..N or 0..N) shall be plural rather than singular.

Example 2:

users

c) Each value of an enumeration type shall be represented using UPPER_WITH_UNDERSCORE.

Example 3:

PROHIBITTED_LISTED

d) The names of data types shall be represented using UpperCamel.

Example 4:

ResourceHandle

5.2 API Definition

5.2.1 Resource Structure

Resource structure shall define the structure of the resource URIs, the resources, the associated HTTP methods and custom operations used for the service.

Figure 5.2.1-1 provides an example of the resource URI structure (i.e. resource tree) of an API. Table 5.2.1-1 provides an example of an overview of the resources defined for the service, and their applicable HTTP methods and custom operations.

Figure 5.2.1-1: Resource URI structure of the <xyz > API

In figure 5.2.1-1 the following graphical conventions are used:

– a child node with a solid-line frame represents:

– a resource-URI that has at least one supported HTTP method associated, see e.g. "/resource A" in Figure 5.2.1-1. Such node may be any of the archetypes defined in Annex C1, C2 and C3;

– a resource-URI, which does not have any standard HTTP operation defined, but has a custom operation, see e.g. "/individual child resource A2" in Figure 5.2.1-1;

– a child node with a dashed-line frame represents a a specific custom operation, see e.g. "/custom operation A3" and "/custom operation C1" in Figure 5.2.1-1. Such node is a Custom operation archetype, see Annex C4;

– a child node without a line around its frame (e.g. "/special node type B" in Figure 5.2.1-1) typically represents a path segment for which no standard HTTP operation is specified. This graphical representation is also used when a custom operation without an associated resource is defined for a path segment. .

Table 5.2.1-1: Resources and methods overview

Resource purpose/name	Resource URI (relative path after API URI)	HTTP method or custom operation	Description (service operation)
<Resource name>	<relative path after API URI>	GET	<Operation executed by GET>
		PUT	<Operation executed by PUT>
		PATCH	<Operation executed by PATCH>
		POST	<Operation executed by POST>
		DELETE	<Operation executed by DELETE>
	<relative path after API URI>/release	release (POST)	<Operation executed by Custom operation>

NOTE 1: The "API URI" is defined in clauses 3.1 and 4.4.1.

For a resource, the "relative path after API URI" is appended to the API URI to form the resource URI as defined in clause 3.1.

5.2.2 Resources and HTTP Methods

Resources and HTTP methods shall specify the resource URI, resource URI variables for the resource and the standard HTTP methods supported by the resource.

Example:

Resource URI: {apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>

The resource URI variables supported by the resource shall be defined as table 5.2.2-1 illustrates.

Table 5.2.2-1: Resource URI variables for the resource

Name	Definition
apiRoot	See clause 4.4.1
< Name of resource URI variables for resource>	< Definition of resource URI variables for resource >

The {apiRoot} URI variable should be defined in clauses and this definition should be referenced to ease a possible update of the apiVersion value.

Each method supported by the resource shall be described including the URI query parameters supported by the method, data structures supported by the request body, and the data structures supported by the response body.

URI query parameters supported by the method shall be defined as table 5.2.2-2 illustrates.

Table 5.2.2-2: URI query parameters supported by a method on the resource

Name	Data type	P	Cardinality	Description	Applicability
<name> or n/a	<type> or <leave empty>	<M, C or O>	0..1 or 1 or 0..N or 1..N or <leave empty>	<only if applicable>

Name: Name of query parameter in URI. If no query parameters are defined for the URI, the name should be marked as "n/a".

Data type: Data type of URI query parameters, i.e. a data type defined in the specification. If no query parameter is defined for the URI, the column is left empty.

P: Presence condition of URI query parameters. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional). If no query parameter is defined for the URI, the column is left empty.

Cardinality: Defines the allowed number of occurrence. It shall be "0..1", "1", "0..N", "1..N" . If no query parameter is defined for the URI, the column is left empty.

Description: Additional information for URI query parameter, i.e. describes the use of the parameter or the presence condition of the parameter and so on.

Applicability: If the URI query parameter is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6.2 of 3GPP TS 29.500 [2], the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the attribute can be used with any feature.

NOTE 1: If no optional features are defined for an API, the applicability column can be omitted for that API.

Data structures supported by the request body of the method shall be specified as table 5.2.2-3 illustrates.

Table 5.2.2-3: Data structures supported by the request body on the resource

Data type	P	Cardinality	Description
"<type>" or "array(<type>)" or "map(<type>)" or n/a	"M", "C" or "O"	"0..1", "1", or "M..N", or <leave empty>	<only if applicable>

Data type: Data type of the data structure in the request body. If the data type is indicated as "<type>", the request body shall be of data type <type>. If the data type is indicated as "array(<type>)", the request body shall be an array (see IETF RFC 8259 [3]) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the request body shall be an object (see IETF RFC 8259 [3]) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If no request body is allowed, the Data type shall be marked as "n/a".

P: Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Cardinality: Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers with M being greater than or equal 0, and N being greater than 0 and M. For data type "<type>", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M". The Cardinality shall be left empty if no request body is allowed.

Description: Additional information for a data structure, i.e. describes the use of the data structure or the presence condition of the data structure and so on.

NOTE 2: The cardinality of "0..N" does not imply that the presence condition of the array or map is optional or conditional, i.e. the presence condition can be "M" while the cardinality is "0..N", the presence condition can be "O" or "C" while the cardinality is "1..N".

Data structures supported by the response body of the method shall be specified as table 5.2.2-4 illustrates.

Table 5.2.2-4: Data structures supported by the response body on the resource

Data type

Cardinality

Response

codes

Description

"<type>" or "array(<type>)" or "map(<type>)" or n/a

"M", "C" or "O"

"0..1", "1", or "M..N", or <leave empty>

Data type: Data type of the data structure in the response body. If the data type is indicated as "<type>", the response body shall be of data type <type>. If the data type is indicated as "array(<type>)", the response body shall be an array (see IETF RFC 8259 [3]) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the response body shall be an object (see IETF RFC 8259 [3]) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If no response body is allowed, the Data type shall be marked as "n/a".

P: Presence condition of a data structure in response body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Response codes: Lists applicable response codes with name from HTTP Status Code Registry at IANA [12]. Mandatory HTTP status codes listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [2] for the corresponding HTTP method shall only be included if specific clarifications in the description part or special data types of the response body are required. Applicable HTTP status codes in addition to the mandatory HTTP status codes listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [2] for the corresponding HTTP method shall be included.

Description: Additional information for a response, i.e. describes the meaning of the success case or meaning of the error case with additional statement regarding error handling.

NOTE 3: The cardinality of "0..N" does not imply that the presence condition of the array or map is optional or conditional, i.e. the presence condition can be "M" while the cardinality is "0..N", the presence condition can be "O" or "C" while the cardinality is "1..N".

5.2.3 Representing RPC as Custom Operations on Resources

Custom operations (RPC-style interaction) may be used on a resource. The description of each custom operation contains the custom operation URI, the HTTP method on which the operation is mapped (typically POST), data structures supported by the request body and the data structures supported by the response body.

An overview of the custom operations on a resource is illustrated in table 5.2.3-1.

Table 5.2.3-1: Custom operation

Custom operation URI	Mapped HTTP method	Description
<custom operation URI>	e.g. POST	<Operation executed by custom operation>

Data structures supported by the request body of the method shall be specified as table 5.2.3-2 illustrates.

Table 5.2.3-2: Data structures supported by the mapped HTTP method request body on the resource

Data type	P	Cardinality	Description
"<type>" or "array(<type>)" or "map(<type>)"	"M", "C" or "O"	"0..1", "1", or "M..N", or <leave empty>	<only if applicable>

P: Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Description: Additional information for a data structure, i.e. describes the use of the data structure or the presence condition of the data structure and so on.

NOTE 1: The cardinality of "0..N" does not imply that the presence condition of the array or map is optional or conditional, i.e. the presence condition can be "M" while the cardinality is "0..N", the presence condition can be "O" or "C" while the cardinality is "1..N".

Data structures supported by the response body of the method shall be specified as table 5.2.3-3 illustrates.

Table 5.2.3-3: Data structures supported by the mapped HTTP method response body on the resource

Data type

Cardinality

Response

codes

Description

"<type>" or "array(<type>)" or "map(<type>)"

"M", "C" or "O"

"0..1", "1" or "M..N", or <leave empty>

P: Presence condition of a data structure in response body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Description: Additional information for a response, i.e. describes the meaning of the success case or meaning of the error case with additional statement regarding error handling.

NOTE 2: The cardinality of "0..N" does not imply that the presence condition of the array or map is optional or conditional, i.e. the presence condition can be "M" while the cardinality is"0..N", the presence condition can be "O" or "C" while the cardinality is "1..N".

5.2.3A Notifications

Notifications based on the Callback URI as specified in clause 4.6.2.3 and clause 6.2 of 3GPP TS 29.500 [2] may be supported. The description of each notification contains the Callback URI, the HTTP method (typically POST), data structures supported by the request body and the data structures supported by the response body.

An overview of the notifications is illustrated in table 5.2.3A-1.

Table 5.2.3A-1: Notifications overview

Notification

Callback URI

HTTP method or custom operation

Description

(service operation)

e.g. Status Change Notification

< Callback URI >

e.g. {StatusCallbackUri}

e.g POST

e.g. Notify Event

Example:

Callback URI: {notifUri}

The callback URI variables shall be defined as table 5.2.3A-2 illustrates.

Table 5.2.3A-2: Callback URI variables

Name	Definition
notifUri	String formatted as URI with the Callback Uri

Data structures supported by the request body of the method shall be specified as table 5.2.3A-3 illustrates.

Table 5.2.3A-3: Data structures supported by the HTTP method request body

Data type	P	Cardinality	Description
"<type>" or "array(<type>)" or "map(<type>)"	"M", "C" or "O"	"0..1", "1", or "M..N", or <leave empty>	<only if applicable>

P: Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Description: Additional information for a data structure, i.e. describes the use of the data structure or the presence condition of the data structure and so on.

Data structures supported by the response body of the method shall be specified as table 5.2.3A-4 illustrates.

Table 5.2.3A-4: Data structures supported by the mapped HTTP method response body

Data type

Cardinality

Response

codes

Description

"<type>" or "array(<type>)" or "map(<type>)"

"M", "C" or "O"

"0..1", "1" or "M..N", or <leave empty>

P: Presence condition of a data structure in response body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Description: Additional information for a response, i.e. describes the meaning of the success case or meaning of the error case with additional statement regarding error handling.

NOTE 2: The cardinality of "0..N" does not imply that the presence condition of the array or map is optional or conditional, i.e. the presence condition can be "M" while the cardinality is"0..N", the presence condition can be "O" or "C" while the cardinality is "1..N".

5.2.4 Data Models

5.2.4.1 General

The application data model supported by the API shall be specified with the following data types:

1. Structured data types

2. Simple data types

3. Enumerations

4. Binary data

5. Data types describing alternative data types

6. Data types describing combinations of data types

Each data type can be specific for the API or common to multiple APIs (offered by the same or different NFs). The common data types shall be specified in 3GPP TS 29.571 [5]. Characters in an enumeration or string data type in both simple and structured/combination data types specific for the API or common to multiple APIs shall be handled as case sensitive by default, unless explicitly specified the IE is case insensitive in specifications, e.g. DNN in 3GPP TS 23.003 [27].

5.2.4.2 Structured data types

The structured data types shall represent an object (see IETF RFC 8259 [3]). The structured data types shall contain attributes that are simple data types, structured data types, arrays (see below), maps (as defined below), enumerations, data types describing alternative data types, data types describing combinations of data types or "Any Type" (as described below).

An array (see IETF RFC 8259 [3]) shall represent a list of values without keys and with significance in the order of sequence. All values shall be of the same type.

A map shall represent an object (see IETF RFC 8259 [3]) with a list of key-value pairs (with no significance in the order of sequence), where all keys are of type string and shall be unique identifiers assigned by the application rather than by the schema, and where all values shall be of the same type.

NOTE 1: Maps are supported by the OpenAPI specification [4] as described at https://swagger.io/docs/specification/data-models/dictionaries/. Maps can enable a faster lookup of elements identified by some key in huge data structures compared to arrays that contain the key within the elements. Maps can also be used instead of arrays to modify individual elements when modification instructions of the PATCH method are compliant to IETF RFC 7396 [7].

Each structured data type shall be specified in a separate clause as illustrated in table 5.2.4.2-1.

Table 5.2.4.2-1: Definition of type <Data type>

Attribute name	Data type	P	Cardinality	Description	Applicability
<attribute name>	"<type>" or "array(<type>)" or "map(<type>)" or "Any Type"	"M", "C" or "O"	"0..1", "1" or "M..N"	<only if applicable>

Table 5.2.4.2-2: Definition of type <Data type> with nested structures

Attribute name	Data type	P	Cardinality	Description	Applicability
<attribute name>	"array(map(<type>)" or "map(array(<type>)" or" array(array(<type>)" or "map(map(<type>)"	"M", "C" or "O"	"M1..N1(M2..N2)"	<only if applicable>

Attribute name: Name of attributes that belong to the specified data type. The attribute names within a structured data type shall be unique, and their relative order inside the structured data type shall not imply any specific ordering of the corresponding JSON elements in a JSON object.

NOTE 2: The JSON specification (IETF RFC 8259 [3]) allows duplicate keys in a JSON object, but its usage is discouraged, since it makes interoperability more difficult, and makes the behavior of the JSON parsing software unpredictable. Similarly, that RFC encourages to make implementations not dependent on attribute ordering.

Data type: Data type of the attribute. If the data type is indicated as "<type>", the attribute shall be of data type <type>. If the data type is indicated as "array(<type>)", the attribute shall be an array (see IETF RFC 8259 [3]) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the attribute shall be an object (see IETF RFC 8259 [3]) encoding a map that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification. If the data type is indicated as "Any Type", the attribute can either be "integer", "number", "string", "boolean", "array" or "object" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification.

P: Presence condition of a data structure in request body. It shall be one of "M" (for Mandatory), "C" (for Conditional) and "O" (for Optional).

Cardinality: Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers; with M being greater than or equal 0, and N being greater than 0 and M. For data type with nested structures, the cardinality is expressed in a nested manner, each level of the M and N values describe the cardinality of the corresponding level of the data structure. For data type "<type>" and "Any Type", the cardinality shall be set to "0..1" if the Presence condition is "C" or "O", and to "1" if the Presence condition is "M".

Description: Describes the meaning and use of the attribute and may contain normative statements.

Applicability: If the attribute is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of 3GPP TS 29.500 [2], the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the attribute can be used with any feature.

NOTE 4: If no optional features are defined for an API, the applicability column can be omitted for that API.

5.2.4.3 Simple data types and enumerations

The simple data types and enumerations can be referenced from data structures. All simple data types and enumerations should map to base types supported by IDL. Simple data types shall be specified as illustrated in table 5.2.4.3-1.

Table 5.2.4.3-1: Simple data types

Type Name	Type Definition	Description	Applicability
	<one simple data type, i.e. boolean, integer, number, or string>

Type Name: The name of the simple data type.

Type Definition: Base types supported by IDL, i.e. Boolean, integer, string and so on.

Description: Additional descriptions for simple data types like range, string length and so on.

Applicability: If the type is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of 3GPP TS 29.500 [2], the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the type can be used with any feature.

NOTE 1: If no optional features are defined for an API, the applicability column can be omitted for that API.

Each enumeration type shall be respectively specified for their elements sets as illustrated in table 5.2.4.3-2.

Table 5.2.4.3-2: Enumeration < EnumType>

Enumeration value	Description	Applicability
Enumeration value 1	The description of this enum value
Enumeration value 2	The description of this other enum value

Enumeration value: Defines the valid values, which can be integer, string or boolean, it is suggested to keep the same value style in one API specification.

Description: Additional descriptions for enumeration attributes, like the meaning and usage of enumeration elements.

Applicability: If the enumeration value is only applicable for optional feature(s) negotiated using the mechanism defined in clause 6.6 of 3GPP TS 29.500 [2], the name of the corresponding feature(s) shall be indicated in this column. If no feature is indicated. the enumeration value can be used with any feature.

NOTE 2: If no optional features are defined for an API, the applicability column can be omitted for that API.

5.2.4.4 Binary Data

5.2.4.5 Data types describing alternative data types or combinations of data types

The data types describing alternative data types or combinations of data types shall represent an OpenAPI schema object using the "oneOf" , "anyOf" or "allOf" keyword to list alternative or to be combined data types (see the OpenAPI specification [4] and https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).

An instance (i.e. a corresponding part of a JSON file to be evaluated against the schema) matches a list of mutually exclusive alternative data types , as described using the OpenAPI "oneOf" keyword, if the instance matches against one and only one of the alternative data types.

NOTE 1: Data types with the same simple data type but different format and/or pattern attributes are mutually exclusive if the corresponding formats and/or patterns are mutually exclusive.

An instance (i.e. a corresponding part of a JSON file to be evaluated against the schema) matches a list of non-exclusive alternative data types, as described using the OpenAPI "anyOf" keyword, if the instance matches against one or more of the alternative data types.

An instance (i.e. a corresponding part of a JSON file to be evaluated against the schema) matches a list of to be combined data types, as described using the OpenAPI "allOf" keyword, if the instance matches against all of the to be combined data types.

The alternative or to be combined data types shall be simple data types, structured data types, arrays (see clause 5.2.4.2), maps (see clause 5.2.4.2), enumerations, data types describing alternative data types, or data types describing combinations of data types.

Each structured data type shall be specified in a separate clause as illustrated in table 5.2.4.2-1.

Table 5.2.4.2-1: Definition of type <Data type> as a list of <"mutually exclusive alternatives" / "non-exclusive alternatives" / "to be combined data types">

Data type	Cardinality	Description	Applicability
"<type>" or "array(<type>)" or "map(<type>)"	"1" or "M..N"	<only if applicable>

Data type: Data type of the alternative or to be combined data type. If the data type is indicated as "<type>", the alternative or to be combined data type shall be of data type <type>. If the data type is indicated as "array(<type>)", the alternative or to be combined data type shall be an array (see IETF RFC 8259 [3]) that contains elements of data type <type>. If the data type is indicated as "map(<type>)", the alternative or to be combined data type shall be an object (see IETF RFC 8259 [3]) encoding a map (see clause 5.2.4.2) that contains as values elements of data type <type>. <type> can either be "integer", "number", "string" or "boolean" (as defined in the OpenAPI specification [4]), or a data type defined in a 3GPP specification.

Cardinality: Defines the allowed number of occurrence of data type <type>. A cardinality of "M..N", is only allowed for data types "array(<type>)" and "map(<type>)" and indicates the number of elements within the array or map; the values M and N can either be the characters "M" and "N", respectively, or integer numbers; with M being greater than or equal 0, and N being greater than 0. For data type "<type>", the cardinality shall be set to "1".

Description: Describes the meaning and use of the attribute and may contain normative statements.

NOTE 2: If no optional features are defined for an API, the applicability column can be omitted for that API.

NOTE 3: Data types describing alternative data types or combinations of data types can only be extended with additional data types in a backward compatible manner if the new data types are associated with an optional feature and the mechanism defined in clause 6.6 of 3GPP TS 29.500 [2] is used to negotiate the support of that optional feature before that new data type is used.

5.2.5 Relation types

5.3 OpenAPI specification files

5.3.1 General

5GC SBI APIs’ OpenAPI specification files shall comply with the OpenAPI specification [4] and with the present clause 5.3.

Each API shall be described in one OpenAPI specification file contained in an Annex of the 3GPP specification that describes the corresponding API. In addition, 3GPP specifications may contain OpenAPI specification file with common data types.

Informative copies of all OpenAPI specification files contained in 3GPP Technical Specifications are available on a Git-based repository hosted in 3GPP Forge, that uses the GitLab software version control system.

The repository is named "5G APIs" and is publicly accessible via the following URI:

https://forge.3gpp.org/rep/all/5G_APIs

5.3.2 Formatting of OpenAPI specification files

The following guidelines shall be used when documenting OpenAPI specification files:

– OpenAPI specification files shall be documented using YAML format (see YAML 1.2 [16]). For specific restrictions on the usage of YAML in OpenAPI, see OpenAPI Specification [4].

– The style used for the specification shall be "PL" (Programming Language).

– The different scopes in the YAML data structures representing collections (objects, arrays…) shall use an indentation of two white spaces.

– Comments may be added by following the standard YAML syntax ("#").

– Tabs shall not be used in OpenAPI specification files (e.g. within description fields).

– "Unbreakable" spaces (UTF-8 ‘NO-BREAK SPACE’ (U+00A0)) shall not be used in OpenAPI specification files (e.g. within description fields). Only "normal" spaces (UTF-8 ‘SPACE’ (U+0020)) shall be allowed.

– Trailing spaces (i.e. white spaces at the end of a line) should not be used in OpenAPI specification files.

5.3.3 Info

The OpenAPI specification file of an API shall contain an "info" object with the title that should be set to the same value as chosen for the API name in the heading of Annex A.x of the corresponding 3GPP TS, and with the version set as described in clause 4.3.

The "info" object shall also include a "description" field, containing the name of the service that the API implements, and the same copyright notice as included in the front page of the corresponding 3GPP TS that specifies the API. The content of the "description" field shall be formatted using the YAML block notation for scalars (i.e. using the "|" character).

EXAMPLE: "info" object with the title, version and description of the API.

info:

title: ‘Nsmf_PDUSession’

version: ‘1.0.0’

description: |

SMF PDUSession Service.

5.3.4 externalDocs

Each OpenAPI specification file shall provide an "externalDocs" object as illustrated in the example below that shall contain:

– within the "description" field the 3GPP TS number, the version number and the name of the 3GPP TS describing the API, and

– within the "url" field a reference to the folder of that TS within the specification archive of the public 3GPP fileserver (i.e. "https://www.3gpp.org/ftp/Specs/archive/<specSeries>/<SpecNumber>/").

The version number in the "externalDocs" object shall be updated each time when the TS version contains new changes to the OpenAPI specification file.

NOTE 1: If a new TS version is provided without any changes to the OpenAPI specification file, the TS version number included in the "description" field of the "externalDocs" field in the OpenAPI specification file is not updated.

NOTE 2: If a new TS version is provided with changes to the OpenAPI specification file, the TS version number included in the "description" field of the "externalDocs" object is updated. However, if the API version in a given release is still the same as in a previous release, the first TS version in the first release that contains that API version is provided as TS version within the "externalDocs" object also in the TS versions of the subsequent releases.

EXAMPLE: "externalDocs" object.

externalDocs:

description: 3GPP TS 29.503 V15.1.0; 5G System; Unified Data Management Services

url: ‘http://www.3gpp.org/ftp/Specs/archive/29_series/29.503/’

5.3.5 Servers

As defined in clause 4.4.1, the API URI consists of {apiRoot}/<apiName>/<apiVersion>. It shall be encoded in the corresponding OpenAPI specification file as "servers" field with {apiRoot} as variable.

Example:

servers:

– url: ‘{apiRoot}/nxxx-yyyy/v1’

variables:

apiRoot:

default: https://example.com

description: apiRoot as defined in clause 4.4.1 of 3GPP TS 29.501

5.3.6 References to other 3GPP-defined OpenAPI specification files

Open API specification files may contain references to fragments of other 3GPP-defined Open API specification files.

Such references shall be formatted to refer to local files stored on the same folder.

NOTE 1: For the purpose of referencing, it is assumed that each OpenAPI specification file contained in a 3GPP specification is stored as separate physical file and that all OpenAPI specification files are stored in the same directory on the local server.

The referenced file names for other 3GPP-defined Open API specification files shall comply with the following convention, unless a specific file name is indicated in the Annex of a 3GPP specification defining an OpenAPI specification file. The file name shall consist of (in the order below):

– the 3GPP specification number in the format "TSxxyyy";

– an "_" character;

– if the OpenAPI specification file contains an API definition: the API name which shall be taken from the heading of the relevant annex A.x as defined in the corresponding 3GPP TS of that API.

– if the OpenAPI specification file contains a definition of CommonData: the string "CommonData"; and

– the string ".yaml".

NOTE 2: The informative copies of OpenAPI specification files contained in 3GPP Technical Specifications at the public 3GPP file server (see clause 5.3.1) follow the above conventions and can be copied into a local folder in order to resolve references.

Such a reference to another OpenAPI specification file shall be interpreted as refering to the related OpenAPI specification file contained in the version of the corresponding 3GPP TS indicated in the reference clause of the specification, i.e. for a non-specific reference the latest version of that 3GPP TS in the same Release as the specification.

EXAMPLE: Reference to Data Type "Xxx" defined in the same file

$ref: ‘#/components/schemas/Xxx’

EXAMPLE: Reference to Data Type "Xxx" defined as Common Data in 3GPP TS 29.571:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/Xxx’

EXAMPLE: Reference to Data Type "Xxx" defined within API "Nudm_UEAU" in 3GPP "TS 29.503":

$ref: ‘TS29503_Nudm_UEAU.yaml#/components/schemas/Xxx’

5.3.7 Server-initiated communication

If an API contains server-initiated communication (see clause 6.2 of 3GPP TS 29.500 [2]), e.g. for notifications as described in clause 4.6.2.3, it should be described as "callbacks" in OpenAPI specification files.

Example:

paths:

/subscriptions:

post:

requestBody:

required: true

content:

application/json:

schema:

type: object

properties:

callbackUrl: # Callback URL

type: string

format: uri

responses:

‘201’:

description: Success

callbacks:

myNotification: # arbitrary name

‘{$request.body#/callbackUrl}’: # refers The callback URL in the POST

post:

requestBody: # Contents of the callback message

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/NotificationBody’

responses: # Expected responses to the callback message

‘204’:

description: xxx

An API description may consist of standalone notifications, i.e., notifications where there is no previous interaction between consumer and producer to create a subscription. In such case, the API shall be documented by including a "dummy" subscription request pseudo-operation that shall not be used by the consumer. In such case, the notification URI may be obtained by the producer by different means (e.g. out of band configuration, or via a separate signaling interaction with the producer, or by querying NRF for the NF Profile of the consumer and looking for a "default notification endpoint").

Example:

paths:

/subscriptions:

post:

# This is a pseudo operation, consumers shall NOT invoke this method!

requestBody:

required: true

content:

application/json:

# Unspecified schema for the JSON body, since this is not used by consumer or producer

schema: {}

responses:

default:

$ref: ‘TS29571_CommonData.yaml#/components/responses/default’

callbacks:

standaloneNotification:

‘{notificationUri}’:

# The URI in {notificationUri} is obtained out of band by the producer

post:

requestBody: # Contents of the callback message

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/NotificationBody’

responses: # Expected responses to the callback message

‘204’:

description: xxx

5.3.8 Describing the body of HTTP PATCH requests

5.3.8.1 General

As described in clause 4.6.1.1.3.2, the bodies of HTTP PATCH requests either use a "JSON Merge Patch" encoding as defined in IETF RFC 7396 [7], or a "JSON Patch" encoding as defined IETF RFC 6902 [8].

It is possible to allow both encodings in a OpenAPI Specification [4] offering both schemas as alternative contents.

NOTE: In Rel-15 a single encoding will be selected for each resource as backward compatibility considerations do not yet apply.

An example OpenAPI specification file offering both PATCH encodings is included in Annex D.

5.3.8.2 JSON Merge Patch

In the OpenAPI Specification [4] file, the content field key of the Request Body Object shall contain "application/merge-patch+json". The content field value is a Media Type Object identifying the applicable patch body Schema Object. The patch body Schema Object may contain structured data types derived from the data types used in the schema to describe a complete representation of the resource in such a manner that attributes that are allowed to be modified are listed in the "properties" validation keyword.

NOTE 1: A derived structured data type is beneficial if the data types used to describe a complete representation of the resource contains mandatory attributes, if attributes are allowed to be removed by the PATCH operation, or if a checking by the OpenAPI tooling that only allowed modifications are done via the "additionalProperties: false" keyword is desired. It also provides a clear description in the OpenAPI specification file to developers which modifications need to be supported.

As an alternative, the data types used in the schema to describe a complete representation of the resource may be used if any attributes that are allowed to be removed are marked as "nullable: true" in that schema.

Any attributes that are allowed to be removed shall be marked as "nullable: true" in the patch body Schema Object.

The "additionalProperties: false" keyword may be set.

NOTE 2: The "additionalProperties: false" keyword enables the OpenAPI tooling to check that only allowed modifications are done. Extensions of the object in future releases are still possible under the assumption that the supported features mechanism is used to negotiate the usage of any new attribute prior to the PATCH invocation. If new optional attributes are expected to be introduced without corresponding supported feature or if PATCH can be used as first operation in an API, the usage of the "additionalProperties: false" keyword is not appropriate.

5.3.8.3 JSON PATCH

In the OpenAPI Specification [4] file, the content field of the key Request Body Object shall contain "application/json-patch+json". The content field value is a Media Type Object identifying the applicable patch body. It may contain a mutually exclusive list (using the "oneOf" keyword) of all allowed modifications as <path, op, value> tuples, where "path" is a string containing a JSON Pointer value referring to a JSON object that is allowed to be modified, "op" is an enumeration of allowed JSON PATCH operations on the JSON object identified by "path" and "value" representing the schema/type of the value that will be updated or added at the JSON object identified by "path". In addition, an open alternative containing an object with no properties may be added using the "anyOf" keyword.

NOTE 1: A mutually exclusive list provides a clear description in the OpenAPI specification file to developers which modifications need to be supported. This is of particular interest if only a limited number of modifications need to be supported. If no open alternative is included, the OpenAPI tooling will also check that only allowed modifications are done.

NOTE 2: The open alternative allows for extensions of the PATCH in scenarios where new optional attributes are expected to be introduced without corresponding supported feature or if PATCH can be used as first operation in an API.

5.3.9 Structured data types

For a structured data type, as defined in clause 5.2.4.2, the OpenAPI Specification [4] file shall contain a definition in the components/schemas clause defining a schema with the name of the structured data type as key.

The schema shall contain:

– "type: object";

– "description: <description>", where <description> is the description of the data type in the table defining the structured data type. The "description" attribute should be provided for all data types, specially if they are frequently reused from the same or other OpenAPI specification files; the "description" attribute shall always be provided for data types defined as maps, with a clear indication of the values (strings) used as key of the map.

– if any attributes in the structured data type are marked as mandatory, a "required" keyword listing those attributes; and

– a "properties" keyword containing for each attribute in the structured data type an entry with the attribute name as key and:

1. if the data type is "<type>":

a. if the data type of the attribute is "string", "number", "integer", or "boolean";

i) a type definition using that data type as value ("type: <data type>"); and

ii) optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type; or

b. otherwise a reference to the data type schema for the data type <data type> of the attribute, i.e. "$ref: ‘#/components/schemas/<data type>‘" if that data type schema is contained in the same OpenAPI specification file and "$ref: ‘<filename>#/components/schemas/<data type>‘" if that data type schema is contained in file <filename> in the same directory on the same server;

2. if the data type is "array(<type>)":

a. a type definition "type: array";

b. an "items:" definition containing:

i). if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or

ii). otherwise a reference to the data type schema for the data type <data type> of the attribute, i.e. "$ref: ‘#/components/schemas/<data type>‘" if that data type schema is contained in the same OpenAPI specification file and "$ref: ‘<filename>#/components/schemas/<data type>‘" if that data type schema is contained in file <filename> in the same directory on the same server;

c. if the cardinality contained an integer value <m> as lower boundary, "minItems: <m>"; and

d. if the cardinality contained an integer value <n> as upper boundary, "maxItems: <n>"; and

e. optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type;

3. if the data type is "map(<type>)":

a. a type definition "type: object"; and

b. an "additionalProperties:" definition containing:

i). if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or

c. if the cardinality contained an integer value <m> as lower boundary, "minProperties: <m>"; and

d. if the cardinality contained an integer value <n> as upper boundary, "maxProperties: <n>"; and

e. "description: <description>", where <description> is the description of the attribute in the table defining the structured data type; the "description" attribute shall always be provided for attributes defined as maps, with a clear indication of the values (strings) used as key of the map.

NOTE: An omission of the "minProperties", and "maxProperties" keywords indicates that no lower or upper boundaries respectively, for the number of properties in an object are defined. An omission of the "minItems", and "maxItems" keywords indicates that no lower or upper boundaries, respectively, for the number of items in an array are defined.

4. if the data type is "Any Type":

a. if no properties to be defined, a pair of curly braces after the attribute name key "<attribute name>: {}", which is shorthand syntax for an arbitrary-type schema; or

b. at least one of the following properties:

i) if null value is allowed, "nullable: true"; or

ii). "description: <description>", where <description> is the description of the attribute in the table defining the structured data type.

In the OpenAPI 3.0.0 Specification [4], the ‘$ref’ keyword must be the only attribute of the JSON object. Therefore it is not allowed to use e.g. a "description" attribute along with the ‘$ref’ keyword. However, if it is deemed necessary, a "description" attribute can be added before or after the ‘$ref’ keyword as a comment, i.e. by adding a comment sign ‘#’ in front of the "description" field.

NOTE: CT4 decides on case-by-case basis when it is deemed necessary to add such a "description" attribute along with the ‘$ref’ keyword.

Example:

Table 5.3.9-1: Definition of type ExampleStructuredType

Attribute name	Data type	P	Cardinality	Description	Applicability
exSimple	ExSimple	M	1	exSimple attribute description
exArrayElements	array(string)	O	0..10	exArrayElements attribute description
exMapElements	map(ExStructure)	M	1..N	exMapElements attribute description
exNestedArray	array(map(string))	M	0..N(1..M)	exNestedArray attribute description
exNestedMap	map(array(string))	O	1..N(2..M)	exNestedMap attribute description
exAnyTypeNullableElement	Any Type	O	0..1	exAnyTypeNullableElement attribute description
exAnyTypeNoDescription	Any Type	O	0..1	n/a

The data structure in table 5.3.9-1 is described in an OpenAPI specification file as follows:

components:

schemas:

ExampleStructuredType:

type: object

description: ExampleStructuredType data type description

required:

– exSimple

– exMapElements

properties:

exSimple:

$ref: ‘#/components/schemas/ExSimple’

exArrayElements:

type: array

items:

type: string

minItems: 0

maxItems: 10

description: exArrayElements attribute description

exMapElements:

type: object

additionalProperties:

# description: commented out description of the additionalProperties

$ref: ‘#/components/schemas/ExStructure’

minProperties: 1

description: exMapElements attribute description, indicating values of the map keys

exNestedArray:

type: array

items:

type: object

additionalProperties:

type: string

minProperties: 1

description: exNestedArray attribute description

exNestedMap:

type: object

additionalProperties:

type: array

items:

type: string

minItems: 2

minProperties: 1

description: exNestedMap attribute description

exAnyTypeNullableElement:

nullable: true

description: exAnyTypeNullableElement attribute description

exAnyTypeNoDescription: {}

5.3.10 Data types describing alternative data types or combinations of data types

For a data type describing alternatives, as defined in clause 5.2.4.5, the OpenAPI Specification [4] file shall contain a definition in the components/schemas clause defining a schema with the name of the data type describing alternatives as key.

The schema shall contain:

– the "oneOf", "anyOf" or "allOf" keyword selected as follows:

1. for table caption "Definition of type <Data type> as a list of mutually exclusive alternatives", the "oneOf" keyword;

2. for table caption "Definition of type <Data type> as a list of non-exclusive alternatives", the "anyOf" keyword;

3. for table caption "Definition of type <Data type> as a list of to be combined data types", the "allOf" keyword;

– a list of alternatives, containing for each line in the table describing the data type a separate line starting with "-":

1. if the data type is "<type>":

a. if the data type of the attribute is "string", "number", "integer", or "boolean";

i) a type definition using that data type as value ("type: <data type>"); and

ii) optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type; or

2. if the data type is "array(<type>)":

a. a type definition "type: array";

b. an "items:" definition containing:

i). if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or

c. if the cardinality contained an integer value <m> as lower boundary, "minItems: <m>"; and

d. if the cardinality contained an integer value <n> as upper boundary, "maxItems: <n>"; and

e. optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type;

3. if the data type is "map(<type>)":

a. a type definition "type: object"; and

b. an "additionalProperties:" definition containing:

i). if the data type of the attribute is "string", "number", "integer", or "boolean", a type definition using that data type as value ("type: <data type>"); or

c. if the cardinality contained an integer value <m> as lower boundary, "minProperties: <m>"; and

d. if the cardinality contained an integer value <n> as upper boundary, "maxProperties: <n>"; and

e. optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type.

Example:

Table 5.3.10-1: Definition of type ExampleAlternativesType as a list of mutually exclusive alternatives

Data type	Cardinality	Description	Applicability
ExSimple	1	exSimple attribute description
array(string)	0..10	exArrayElements attribute description
map(ExStructure)	1..N	exMapElements attribute description

The data structure in table 5.3.10-1 is described in an OpenAPI specification file as follows:

components:

schemas:

ExampleAlternativesType:

oneOf:

– $ref: ‘#/components/schemas/ExSimple’

– type: array

items:

type: string

minItems: 0

maxItems: 10

description: exArrayElements attribute description

– type: object

additionalProperties:

$ref: ‘#/components/schemas/ExStructure’

minProperties: 1

description: exMapElements attribute description

5.3.11 Error Responses

As described in clause 4.8 of the present specification and clause 5.2.7 of 3GPP TS 29.500 [2], 5GC SBI APIs use valid HTTP response codes as error codes in HTTP responses and may include a "ProblemDetails" data structure specified in clause 5.2.4.1 of 3GPP TS 29.571 [5] or an application-specific data structure.

Table 5.2.7.1-1 of 3GPP TS 29.500 [2] specifies HTTP status code per HTTP method. For each HTTP method of an API, HTTP status codes shall be specified using response code tables as described in clauses 5.2.2 and 5.2.3. OpenAPI specification files shall include in the description of an HTTP method in the "paths" segment the mandatory HTTP status codes in Table 5.2.7.1-1 of 3GPP TS 29.500 [2] and the HTTP status codes listed in response codes table of that HTTP method.

For the purpose of referencing, HTTP error responses with "ProblemDetails" data structure are specified as part of the CommonData OpenAPI specification file in Annex A of 3GPP TS 29.571 [5].

Example:

In the example below, the 400, 500 and default error response descriptions defined in 3GPP TS 29.571 [5] are referenced.

paths:

/users:

get:

responses:

‘200’:

content:

application/json

schema:

$ref: ‘#/components/schemas/ExampleGetBody’

‘400’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/400’

‘500’:

$ref: ‘TS29571_CommonData.yaml#/components/responses/500’

default:

$ref: ‘TS29571_CommonData.yaml#/components/responses/default’

The following definitions provided in Annex A of 3GPP TS 29.571 [5] are used in that example:

components:

responses:

‘400’:

description: Bad request

content:

application/problem+json:

schema:

$ref: ‘#/components/schemas/ProblemDetails’

‘500’:

description: Internal Server Error

content:

application/problem+json:

schema:

$ref: ‘#/components/schemas/ProblemDetails’

default:

description: Generic Error

5.3.12 Enumerations

For enumerations, as defined in clause 5.2.4.3, the OpenAPI Specification [4] file shall contain a definition in the components/schemas clause defining a schema with the name of the enumeration as key.

The schema

– shall contain the "anyOf" keyword listing as alternatives:

1. the "type: string" keyword and the "enum" keyword with a list of all defined values for the enumeration; and

2. the "type: string" keyword and the "description" keyword with a description stating that the string is only provided for forward compatibility with future extensions but is not used to encode contents defined in the present version of the specification. Future extensions may need to be defined in conjunction with the supported feature mechanism as specified in clause 6.6.2 of 3GPP TS 29.500 [2], and

– should contain a description field, containing the overall meaning and purpose of the enumeration; additionally, this field may contain a list of the defined values of the enumeration together with explanations of those values.

NOTE: The "enum" keyword restricts the permissible values of the string to the enumerated ones. This can lead to extensibility problems when new values need to be introduced.

Example:

ExampleEnumeration represents xxx, and it is used to indicate yyy or zzz; it complies with the provisions defined in Table 5.3.12-1

Table 5.3.12-1: Enumeration ExampleEnumeration

Enumeration value	Description	Applicability
"ONE"	Value One description
"TWO"	Value Two description

The data structure in table 5.3.12-1 is described in an OpenAPI specification file as follows:

components:

schemas:

ExampleEnumeration:

anyOf:

– type: string

enum:

– ONE

– TWO

– type: string

description: >

This string provides forward-compatibility with future

extensions to the enumeration but is not used to encode

content defined in the present version of this API.

description: |

ExampleEnumeration represents xxx, and it is used to indicate yyy or zzz;

it complies with the provisions defined in Table 5.3.12-1 of 3GPP TS ab.cde.

Possible values are:

– ONE: Value One description

– TWO: Value Two description

5.3.13 Formatting of structured data types in query parameters

Structured data types shall represent JSON objects or arrays.

When used in query parameters of a URI, the following formatting shall be used:

– JSON objects and arrays of JSON objects: they shall be formatted using the JSON syntax, which is specified in OpenAPI Specification [4] by including a "content:" block, and specifying the "application/json" media type, followed by the OpenAPI definition of the object.

EXAMPLE:

– name: plmn-id

in: query

content:

application/json:

schema:

type: object

properties:

mcc:

type: string

mnc:

type: string

This results in the following formatting:

…/resource?plmn-id={"mcc":"123","mnc":"456"}

– Arrays of simple types: they shall be formatted using the OpenAPI "style" keyword set to "form" and the "explode" keyword set to "false".

EXAMPLE:

– name: service-names

in: query

style: form

explode: false

schema:

type: array

items:

type: string

This results in the following formatting:

…/resource?service-names=service1,service2,service3

As described in 3GPP TS 29.500 [2], clause 5.2.10, when the URI is composed, it shall escape (percent-encode) certain "reserved" characters. When an array of strings is formatted with "explode: false" keyword, the COMMA (U+002C) character is used as separator of the different string values; this implies that this character (the value separator) shall not be escaped, while any other comma used inside the different string values shall be escaped (percent-encoded).

5.3.14 Attribute Presence Conditions

In an OpenAPI Specification [4], presence conditions for attributes in a JSON schema definition shall be expressed by using the "required" keyword, indicating a list (array) of attributes that shall always be present in an object conforming to such schema.

The "required" keyword may be used as part of any of the expressions defined by OpenAPI to combine schemas ("oneOf", "anyOf", "allOf", "not").

EXAMPLES:

– JSON object defining attributes "a" and "b", of type integer, where attribute "a" shall always be present:

components:

schemas:

ExampleType1:

type: object

required: [ a ]

properties:

type: integer

– JSON object defining attributes "a" and "b", of type integer, where at least one of them, or both, shall be present:

components:

schemas:

ExampleType2:

type: object

anyOf:

– required: [ a ]

– required: [ b ]

properties:

type: integer

– JSON object defining attributes "a" and "b", of type integer, where at least one of them shall be present, but not both:

components:

schemas:

ExampleType3:

type: object

oneOf:

– required: [ a ]

– required: [ b ]

properties:

type: integer

– JSON object defining attributes "a" and "b", of type integer, where "a" and "b" can be both absent but, if one of them is present, the other shall be absent:

components:

schemas:

ExampleType4:

type: object

not:

required: [ a, b ]

properties:

type: integer

– JSON object defining attributes "a" and "b", of type integer, where "b" shall be present if "a" takes a given value (e.g., value 1), but may be absent otherwise:

components:

schemas:

ExampleType5:

type: object

properties:

type: integer

anyOf:

– not:

required: [ a ]

properties:

type: integer

enum: [ 1 ]

– required: [ b ]

– JSON object defining attributes "a" and "b", of type integer, where "b" shall be present if and only if "a" takes a given value (e.g., value 1):

components:

schemas:

ExampleType6:

type: object

properties:

type: integer

oneOf:

– required: [ a ]

properties:

type: integer

enum: [ 1 ]

– not:

required: [ b ]

– JSON object defining attributes "a", "b", "c" and "d", of type integer, where none of the pairs ("a" and "b") and ("c" and "d") shall be present:

components:

schemas:

ExampleType7:

type: object

properties:

type: integer

allOf:

– not:

required: [ a, b ]

– not:

required: [ c, d ]

NOTE: Object schema definitions should not have property names in the "required" attribute for which a corresponding property definition does not exist.

5.3.15 Usage of the "tags" field

In an OpenAPI specification, all HTTP operations belonging to the same resource should include a "tags" field containing a same value, briefly describing that resource (e.g. using the name of the resource and its archetype). This results in all operations being grouped by the User Interface of OpenAPI tools, which helps with readibility of the API documentation.

EXAMPLE:

openapi: 3.0.0

(…)

paths:

/nf-instances/{nfInstanceID}:

get:

summary: Read the profile of a given NF Instance

operationId: GetNFInstance

tags:

– NF Instance ID (Document)

(…)

put:

summary: Register a new NF Instance

operationId: RegisterNFInstance

tags:

– NF Instance ID (Document)

(…)

patch:

summary: Update NF Instance profile

operationId: UpdateNFInstance

tags:

– NF Instance ID (Document)

(…)

5.3.16 Security

As indicated in 3GPP TS 33.501 [22] and 3GPP TS 29.500 [2], the access to an 5GC API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [n3]), based on local configuration. 5GC APIs thus need to support the OAuth2 protocol.

To reflect this, the OpenAPI specification file of an API shall contain:

– a top-level "security" field, that applies to the overall API unless overridden by a resource/operation-level "security" field, listing as alternatives:

i) "{}" to indicate that usage of security is optional; and

ii) the name of the security scheme for oAuth2, including in the array of scopes the name of the API as the only scope; and optionally

– a resource/operation-level "security" field, that applies to a specific operation on a specific resource, and overrides the top-level "security" field, listing as alternatives:

i) "{}" to indicate that usage of security is optional; and

ii) the name of the security scheme for oAuth2, including in the array of scopes the name of the API as the only scope, and

iii) the name of the security scheme for oAuth2, including in the array of scopes the name of the API and the name of one scope to be used to invoke the specific resource/operation, and optionally

iv) the name of the security scheme for oAuth2, including in the array of scopes the name of the API and the names of two scopes to be used to invoke the specific resource/operation, and

NOTE: the option iv) can be used e.g. to define one scope for a set of specific resources, and a second scope for a specific operation within the set.

– a "securitySchemes" field in the "components" clause defining a security schema for oAuth2 as follows:

i) to be of type "oauth2"; and

ii) with a "flows" field containing a "clientCredentials" field that contains:

1) a "tokenUrl" field pointing to the Access Token Request service provided by the NRF (see 3GPP TS 29.510 [18]); and

2) a "scopes" field defining all the different scopes applicable to this API, which includes the name of the corresponding API (using the format used within URIs of that API) to be used as the scope required to get access to the overall API, and also including those resource/operation-level scopes to be used as scopes required to invoke a specific operation on a specific resource.

The naming of the resource/operation-level scopes should consist of the concatenation of the service name, a string or sequence of strings representing a resource name or set of resource names or custom operation, and optionally a string indicating the type of access (e.g. read/modify/create), separated by the ":" (colon) character.

Such last string component of the resource/operation-level scope, that represents the type of access for a resource, should comply with the following principles:

– "read": for GET operations for any resource archetype,

– "create": for POST or PUT operations that result in a creation of new resources from a collection or store resource,

– "modify": for PUT, PATCH or DELETE operations that result on an update or deletion of a document resource,

– "invoke": for POST operations that result in the invocation of a custom operation

– "write": for any operation that results in creation, modification or deletion of resource representations.

Example 1:

security:

– {}

– oAuth2ClientCredentials:

– nnrf-nfm

paths:

/nf-instances:

get:

security:

– {}

– oAuth2ClientCredentials:

– nnrf-nfm

– oAuth2ClientCredentials:

– nnrf-nfm

– nnrf-nfm:nf-instances:read

parameters:

(…)

responses:

(…)

components:

securitySchemes:

oAuth2ClientCredentials:

type: oauth2

flows:

clientCredentials:

tokenUrl: ‘{nrfApiRoot}/oauth2/token’

scopes:

nnrf-nfm: Access to the Nnrf_NFManagement API

nnrf-nfm:nf-instances:read: Read access to the NF Instances (Collection) resource

Example 2:

security:

– {}

– oAuth2ClientCredentials:

– nudr-dr

paths:

/exposure-data/{ueId}/access-and-mobility-data:

get:

security:

– {}

– oAuth2ClientCredentials:

– nudr-dr

– oAuth2ClientCredentials:

– nudr-dr

– nudr-dr:exposure-data

– oAuth2ClientCredentials:

– nudr-dr

– nudr-dr:exposure-data

– nudr-dr:exposure-data:read

parameters:

(…)

responses:

(…)

components:

securitySchemes:

oAuth2ClientCredentials:

type: oauth2

flows:

clientCredentials:

tokenUrl: ‘{nrfApiRoot}/oauth2/token’

scopes:

nudr-dr: Access to the Nudr_DataRepository API

nudr-dr:exposure-data: Access to the ExposureData data set

nudr-dr:exposure-data:read: Access to read ExposureData

5.3.17 Reuse of Structured Data Types

As indicated in clause 5.2.4.1, common data types can be defined in 3GPP TS 29.571 [5], in order to avoid the duplication of data type definitions across multiple APIs.

When such data types are of type object, a given API may require that the common data type is extended with additional attributes, on top of those from the original definition in 3GPP TS 29.571 [5].

In such case, the new data type in that API should not re-define entirely the common data type, and instead, it should use appropriate constructs in OpenAPI (i.e. the "allOf" keyword) to indicate that the new data type contains all the attributes form the common data type, by referencing to it, and indicate the additional attributes needed in the new data type.

EXAMPLE:

The ProblemDetails data type is defined in 3GPP TS 29.571 [5] as:

ProblemDetails:

type: object

properties:

type:

$ref: ‘#/components/schemas/Uri’

title:

type: string

status:

type: integer

detail:

type: string

instance:

$ref: ‘#/components/schemas/Uri’

cause:

type: string

invalidParams:

type: array

items:

$ref: ‘#/components/schemas/InvalidParam’

minItems: 1

Then, if a given API needs to extend ProblemDetails with an additional attribute, e.g. "action" of type string, it should define, e.g. an ExtendedProblemDetails data type as follows:

ExtendedProblemDetails:

allOf:

– $ref: ‘TS29571_CommonData.yaml#/components/schemas/ProblemDetails’

– $ref: ‘#/components/schemas/ProblemDetailsExtension’

ProblemDetailsExtension:

type: object

properties:

action:

type: string

5.3.18 Operation identifiers

Service operations defined in an OpenAPI specification file should be assigned an Operation ID.

EXAMPLE:

get:

operationId: ReadInfo

summary: Read Information.

tags:

– Information (Document)

parameters:

– name: infoType

in: path

description: Requested information Type

required: true

schema:

type: string

(…)

5.3.19 Formatting of description fields

As indicated in OpenAPI Specification [4], "description" fields support the CommonMark Markdown formatting (see https://spec.commonmark.org/0.27).

In the 3GPP APIs, a description field may consist of multiple lines of YAML text; in order to have a proper output formatting (i.e., to be correctly rendered by tooling producing, e.g., HTML-based content), they should be documented as follows:

– If line breaks need to be kept in the output formatting, this shall be indicated by two trailing white spaces (see https://spec.commonmark.org/0.27/#hard-line-breaks). Those are represented in the example below as gray-shaded non-break spaces for illustration purposes, but the YAML file shall contain two normal white spaces:

description: |

Text in the first line.

More text in the second line.

Additional text in the third line.

– If the text in the different lines should be formatted as a bulleted HTML list, each line may be prepended by the hyphen "-" character, as follows:

description: |

Text in the first line:

– List item 1

– List item 2

– If the text should be displayed in the output formatting as a single line, the YAML file may be formatted using one of the following options:

– All text in a single YAML line, following the "description" keyword, such as:

description: This is a long description text that is formatted as a single YAML line, which is correct, but may not be optimal when the YAML file is displayed on a text editor configured to not automatically wrap long lines.

– The "description" keyword is followed by the ">" character and the text is placed in different lines (this option should be the preferred approach, rather than having extremely long lines in the YAML file), such as:

description: >

This text is the first part of a single line,

followed by this second line,

where all these 3 lines will be displayed in the same line in the output formatting.