Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TS 29.501  Word version:  16.4.0

Top   Top   Up   Prev   Next
1…   4…   4.6…   4.7…   5…   5.3…   6…   A…

 

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 ETSI 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.etsi.org/rep/3GPP/5G_APIs
Up
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 3.0.0 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 ("#").
Up
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.
    © 2019, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.
Up
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.
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/
Up
5.3.5  ServersWord‑p. 52
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 clause 4.4.1 of TS 29.501
Up
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.
The referenced file names for other 3GPP-defined Open API specification filesshall 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:
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'
Up
5.3.7  Server-initiated communicationWord‑p. 53
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
                '200':
                  description: xxx
Up
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 RFC 7396, or a "JSON Patch" encoding as defined RFC 6902.
It is possible to allow both encodings in a OpenAPI Specification [4] offering both schemas as alternative contents.
An example OpenAPI specification file offering both PATCH encodings is included in Annex D.
Up
5.3.8.2  JSON Merge PatchWord‑p. 54
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.
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.
Up
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.
Up
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";
  • 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.
    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.
Example:
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
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
      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:
            $ref: '#/components/schemas/ExStructure'
          minProperties: 1
          description: exMapElements attribute description
        exAnyTypeNullableElement:
          nullable: true
          description: exAnyTypeNullableElement attribute description
        exAnyTypeNoDescription: {}
Up
5.3.10  Data types describing alternative data types or combinations of data typesWord‑p. 56
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:
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
Up
5.3.11  Error ResponsesWord‑p. 58
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
Up
5.3.12  EnumerationsWord‑p. 59
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 extensibility and is not used to encode contents defined in the present version of the specification. and
  • may contain a description listing the defined values of the enumeration together with explanations of those values.
Example:
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: >
        Possible values are
        - One: Value One description
        - Two: Value Two description
Up
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 [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
    
Up
5.3.14  Attribute Presence ConditionsWord‑p. 60
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 ]
    
Up
5.3.15  Usage of the "tags" fieldWord‑p. 62
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)
    (...)
Up
5.3.16  Security
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 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:
    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 the scope 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 "tokenUri" 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 shall consist of the concatenation of the service name, a string representing the resource name or custom operation, and 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.
Example:
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
Up
5.3.17  Reuse of Structured Data TypesWord‑p. 63
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
Up

Up   Top   ToC