Content for  TS 29.501  Word version:  19.0.0

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: In that case, the TS does not contain OpenAPI descriptions in normative Annexes and instead it includes information about the repository used for the storage of OpenAPI files, e.g., GitLab group, repository name, branch, directory path (if any), and a Git tag representing the repository snapshot that corresponds to the specific TS version.

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.

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:
  title: 'Nsmf_PDUSession'
  version: '1.0.0'
  description: |
    SMF PDUSession Service.
    © 2020, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.

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

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/'

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 TS 29.501

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

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

If an API contains server-initiated communication (see clause 6.2 of TS 29.500), 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

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>":
     1. if the data type of the attribute is "string", "number", "integer", or "boolean";
        1. a type definition using that data type as value ("type: <data type>"); and
        2. optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type; or
     2. 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>)":
     1. a type definition "type: array";
     2. an "items:" definition containing:
        1. 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
        2. 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;
     3. if the cardinality contained an integer value <m> as lower boundary, "minItems: <m>"; and
     4. if the cardinality contained an integer value <n> as upper boundary, "maxItems: <n>"; and
     5. 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>)":
     1. a type definition "type: object"; and
     2. an "additionalProperties:" definition containing:
        1. 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
        2. 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;
     3. if the cardinality contained an integer value <m> as lower boundary, "minProperties: <m>"; and
     4. if the cardinality contained an integer value <n> as upper boundary, "maxProperties: <n>"; and
     5. "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.
  4. if the data type is "Any Type":
     1. 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
     2. at least one of the following properties:
        1. if null value is allowed, "nullable: true"; or
        2. "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. Example:

  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
    exNestedArray:
     type: array
     items:
      type: object
      additionalProperties:
       type: string
      minProperties: 1
     description: exMapElements attribute description, indicating values of the map keys
    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: {}

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>":
     1. if the data type of the attribute is "string", "number", "integer", or "boolean";
        1. a type definition using that data type as value ("type: <data type>"); and
        2. optionally "description: <description>", where <description> is the description of the attribute in the table defining the structured data type; or
     2. 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>)":
     1. a type definition "type: array";
     2. an "items:" definition containing:
        1. 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
        2. 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;
     3. if the cardinality contained an integer value <m> as lower boundary, "minItems: <m>"; and
     4. if the cardinality contained an integer value <n> as upper boundary, "maxItems: <n>"; and
     5. 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>)":
     1. a type definition "type: object"; and
     2. an "additionalProperties:" definition containing:
        1. 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
        2. 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;
     3. if the cardinality contained an integer value <m> as lower boundary, "minProperties: <m>"; and
     4. if the cardinality contained an integer value <n> as upper boundary, "maxProperties: <n>"; and
     5. optionally "description: <description>", where <description> is the description of the attribute in the Table defining the structured data type.

Example:

  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

As described in clause 4.8 of the present specification and clause 5.2.7 of TS 29.500, 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 TS 29.571 or an application-specific data structure. Table 5.2.7.1-1 of TS 29.500 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 TS 29.500 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 TS 29.571. Example: In the example below, the 400, 500 and default error response descriptions defined in TS 29.571 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 TS 29.571 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

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 TS 29.500, 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.

Example:

  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

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 clause 5.2.10 of TS 29.500, 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).

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:
      a:
       type: integer
      b:
       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:
      a:
       type: integer
      b:
       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:
      a:
       type: integer
      b:
       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:
      a:
       type: integer
      b:
       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:
      a:
       type: integer
      b:
       type: integer
     anyOf:
      - not:
        required: [ a ]
        properties:
         a:
          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:
      a:
       type: integer
      b:
       type: integer
     oneOf:
      - required: [ a ]
       properties:
        a:
         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:
      a:
       type: integer
      b:
       type: integer
      c:
       type: integer
      d:
       type: integer
     allOf:
      - not: 
        required: [ a, b ]
      - not: 
        required: [ c, d ]
  

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

As indicated in TS 33.501 and TS 29.500, the access to an 5GC API may be authorized by means of the OAuth2 protocol (see RFC 6749), 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:
  1. "{}" to indicate that usage of security is optional; and
  2. 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:
  1. "{}" to indicate that usage of security is optional; and
  2. the name of the security scheme for oAuth2, including in the array of scopes the name of the API as the only scope, and
  3. 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
  4. 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
• a "securitySchemes" field in the "components" clause defining a security schema for oAuth2 as follows:
  1. to be of type "oauth2"; and
  2. 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 TS 29.510); 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

As indicated in clause 5.2.4.1, common data types can be defined in TS 29.571, 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 TS 29.571. 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 TS 29.571 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

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

(…)

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.