openapi: 3.0.0
info:
  title: 3gpp-service-parameter
  version: 1.1.3
  description: |
    API for AF service paramter  
    © 2023, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
externalDocs:
  description: >
    3GPP TS 29.522 V17.9.0; 5G System; Network Exposure Function Northbound APIs.
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.522/'
security:
  - {}
  - oAuth2ClientCredentials: []
servers:
  - url: '{apiRoot}/3gpp-service-parameter/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.

paths:
  /{afId}/subscriptions:
    parameters:
      - name: afId
        in: path
        description: Identifier of the AF
        required: true
        schema:
          type: string
    get:
      summary: read all of the active subscriptions for the AF
      operationId: ReadAllSubscriptions
      tags:
        - Service Parameter Subscriptions
      parameters:
        - name: gpsis
          in: query
          description: The GPSI of the requested UE(s).
          required: false
          schema:
            type: array
            items:
              $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
            minItems: 1
        - name: ip-addrs
          in: query
          description: The IP address(es) of the requested UE(s).
          required: false
          schema:
            type: array
            items:
              $ref: 'TS29571_CommonData.yaml#/components/schemas/IpAddr'
            minItems: 1
        - name: ip-domain
          in: query
          description: >
            The IPv4 address domain identifier. The attribute may only be provided
            if IPv4 address is included in the ip-addrs query parameter.
          required: false
          schema:
            type: string
        - name: mac-addrs
          in: query
          description: The MAC address(es) of the requested UE(s).
          required: false
          schema:
            type: array
            items:
              $ref: 'TS29571_CommonData.yaml#/components/schemas/MacAddr48'
            minItems: 1
      responses:
        '200':
          description: OK. 
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceParameterData'
                minItems: 0
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '406':
          $ref: 'TS29122_CommonData.yaml#/components/responses/406'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    post:
      summary: Creates a new subscription resource 
      operationId: CreateAnSubscription
      tags:
        - Service Parameter Subscriptions
      requestBody:
        description: Request to create a new subscription resource
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceParameterData'
      responses:
        '201':
          description: Created (Successful creation of subscription)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceParameterData'
          headers:
            Location:
              description: Contains the URI of the newly created resource.
              required: true
              schema:
                type: string
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'
      callbacks:
        notificationDestination:
          '{$request.body#/notificationDestination}':
            post:
              requestBody:
                description: >
                  Notifications upon AF Service Parameter Authorization Update,
                  and/or AF subscribed event notification of the outcome related
                  to the invocation of service parameters provisioning.
                required: true
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/AfNotification'
                      minItems: 1
              responses:
                '204':
                  description: Expected response to a successful callback processing without a body
                '307':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/307'
                '308':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/400'
                '401':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/401'
                '403':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/500'
                '503':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29122_CommonData.yaml#/components/responses/default'

  /{afId}/subscriptions/{subscriptionId}:
    parameters:
      - name: afId
        in: path
        description: Identifier of the AF
        required: true
        schema:
          type: string
      - name: subscriptionId
        in: path
        description: Identifier of the subscription resource
        required: true
        schema:
          type: string
    get:
      summary: read an active subscriptions for the SCS/AS and the subscription Id
      operationId: ReadAnSubscription
      tags:
        - Individual Service Parameter Subscription
      responses:
        '200':
          description: OK (Successful get the active subscription)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceParameterData'
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '406':
          $ref: 'TS29122_CommonData.yaml#/components/responses/406'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    put:
      summary: Fully updates/replaces an existing subscription resource
      operationId: FullyUpdateAnSubscription
      tags:
        - Individual Service Parameter Subscription
      requestBody:
        description: Parameters to update/replace the existing subscription
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceParameterData'
      responses:
        '200':
          description: OK (Successful update of the subscription)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceParameterData'
        '204':
          description: OK (Successful update of the subscription)
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    patch:
      summary: Partial updates/replaces an existing subscription resource
      operationId: PartialUpdateAnSubscription
      tags:
        - Individual Service Parameter Subscription
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ServiceParameterDataPatch'
      responses:
        '200':
          description: OK. The subscription was modified successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceParameterData'
        '204':
          description: OK. The subscription was modified successfully.
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    delete:
      summary: Deletes an already existing subscription
      operationId: DeleteAnSubscription
      tags:
        - Individual Service Parameter Subscription
      responses:
        '204':
          description: No Content (Successful deletion of the existing subscription)
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}
  schemas: 
    ServiceParameterData:
      description: Represents an individual Service Parameter subscription resource.
      type: object
      properties:
        afServiceId:
          type: string
          description: Identifies a service on behalf of which the AF is issuing the request.
        appId:
          type: string
          description: Identifies an application.
        dnn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
        snssai:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Snssai'
        externalGroupId:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/ExternalGroupId'
        anyUeInd:
          type: boolean
          description: >
            Identifies whether the AF request applies to any UE. This attribute
            shall set to "true" if applicable for any UE, otherwise, set to "false".
        gpsi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
        ueIpv4:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv4Addr'
        ueIpv6:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Ipv6Addr'
        ueMac:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/MacAddr48'
        self:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Link'
        subNotifEvents:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          minItems: 1
        notificationDestination:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        requestTestNotification:
          type: boolean
          description: >
            Set to true by the AF to request the NEF to send a test notification
            as defined in clause 5.2.5.3 of 3GPP TS 29.122. Set to false or omitted otherwise.
        websockNotifConfig:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig'
        paramOverPc5:
          $ref: '#/components/schemas/ParameterOverPc5'
        paramOverUu:
          $ref: '#/components/schemas/ParameterOverUu'
        paramForProSeDd:
          $ref: '#/components/schemas/ParamForProSeDd'
        paramForProSeDc:
          $ref: '#/components/schemas/ParamForProSeDc'
        paramForProSeU2NRelUe:
          $ref: '#/components/schemas/ParamForProSeU2NRelUe'
        paramForProSeRemUe:
          $ref: '#/components/schemas/ParamForProSeRemUe'
        urspGuidance:
          type: array
          items:
            $ref: '#/components/schemas/UrspRuleRequest'
          minItems: 1
          description: Contains the service parameter used to guide the URSP.
        mtcProviderId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/MtcProviderInformation'
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
    ServiceParameterDataPatch:
      description: >
        Represents the parameters to request the modification of a service parameter
        subscription resource.
      type: object
      properties:
        paramOverPc5:
          $ref: '#/components/schemas/ParameterOverPc5Rm'
        paramOverUu:
          $ref: '#/components/schemas/ParameterOverUuRm'
        paramForProSeDd:
          $ref: '#/components/schemas/ParamForProSeDdRm'
        paramForProSeDc:
          $ref: '#/components/schemas/ParamForProSeDcRm'
        paramForProSeU2NRelUe:
          $ref: '#/components/schemas/ParamForProSeU2NRelUeRm'
        paramForProSeRemUe:
          $ref: '#/components/schemas/ParamForProSeRemUeRm'
        urspGuidance:
          type: array
          items:
            $ref: '#/components/schemas/UrspRuleRequest'
          minItems: 1
          description: Contains the service parameter used to guide the URSP.
        subNotifEvents:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          minItems: 1
          nullable: true
        notificationDestination:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
    ParameterOverPc5:
      description: >
        Represents configuration parameters for V2X communications over PC5 reference point.
      type: string
    ParameterOverPc5Rm:
      description: >
        Represents the same as the ParameterOverPc5 data type but with the nullable:true property.
      type: string
      nullable: true
    ParameterOverUu:
      description: >
        Represents configuration parameters for V2X communications over Uu reference point.
      type: string
    ParameterOverUuRm:
      description: >
        Represents the same as the ParameterOverUu data type but with the nullable:true property.
      type: string
      nullable: true
    ParamForProSeDd:
      description: Represents the service parameters for 5G ProSe direct discovery.
      type: string
    ParamForProSeDdRm:
      description: >
        This data type is defined in the same way as the ParamForProSeDd data type,
        but with the OpenAPI nullable property set to true.
      type: string
      nullable: true
    ParamForProSeDc:
      description: Represents the service parameters for 5G ProSe direct communications.
      type: string
    ParamForProSeDcRm:
      description: >
        This data type is defined in the same way as the ParamForProSeDc data type,
        but with the OpenAPI nullable property set to true.
      type: string
      nullable: true
    ParamForProSeU2NRelUe:
      description: Represents the service parameters for 5G ProSe UE-to-network relay UE.
      type: string
    ParamForProSeU2NRelUeRm:
      description: >
        This data type is defined in the same way as the ParamForProSeU2NRelay data type,
        but with the OpenAPI nullable property set to true.
      type: string
      nullable: true
    ParamForProSeRemUe:
      description: Represents the service parameters for 5G ProSe Remate UE.
      type: string
    ParamForProSeRemUeRm:
      description: >
        This data type is defined in the same way as the ParamForProSeRemUe data type,
        but with the OpenAPI nullable property set to true.
      type: string
      nullable: true
    UrspRuleRequest:
      description: Contains parameters that can be used to guide the URSP.
      type: object
      properties:
        trafficDesc:
          $ref: '#/components/schemas/TrafficDescriptorComponents'
        relatPrecedence:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        routeSelParamSets:
          type: array
          items:
            $ref: '#/components/schemas/RouteSelectionParameterSet'
          minItems: 1
          description: >
            Sets of parameters that may be used to guide the Route Selection Descriptors of the 
            URSP.
    RouteSelectionParameterSet:
      description: >
        Contains parameters that can be used to guide the Route Selection
        Descriptors of the URSP.
      type: object
      properties:
        dnn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
        snssai:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Snssai'
        precedence:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        spatialValidityAreas:
          type: array
          items:
            $ref: 'TS29522_AMPolicyAuthorization.yaml#/components/schemas/GeographicalArea'
          minItems: 1
          description: >
            Indicates where the route selection parameters apply. It may correspond
            to a geographical area, for example using a geographic shape that
            is known to the AF and is configured by the operator to correspond to a list
            of or TAIs.
        spatialValidityTais:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Tai'
          minItems: 1
          description: >
            Indicates the TAIs in which the route selection parameters apply. This attribute is 
            applicable only within the 5GC and it shall not be included in the request messages of 
            untrusted AFs for URSP guidance.
    Event:
      anyOf:
      - type: string
        enum:
          - SUCCESS_UE_POL_DEL_SP
          - UNSUCCESS_UE_POL_DEL_SP
      - type: string
        description: >
          This string identifies AF subscribe to event(s) notifications related to
          AF provisioned service parameters.
      description: |
        Possible values are:
        - SUCCESS_UE_POL_DEL_SP: Successful UE Policy Delivery related to 
          the invocation of AF provisioned Service Parameters.
        - UNSUCCESS_UE_POL_DEL_SP: Unsuccessful UE Policy Delivery related to the invocation of AF
           provisioned Service Parameters.
    AfNotification:
      description: >
        Notifications upon AF Service Parameter Authorization Update e.g. to
        revoke the authorization, and/or AF subscribed event notification of the
        outcome related to the invocation of service parameter provisioning.
      type: object
      properties:
        subscription:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Link'
        reportEvent:
          $ref: '#/components/schemas/Event'
        authResult:
          $ref: '#/components/schemas/AuthorizationResult'
        gpsis:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
          minItems: 1
        dnn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
        snssai:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Snssai'
        eventInfo:
          $ref: '#/components/schemas/EventInfo'
      required:
        - subscription
      anyOf:
        - required: [reportEvent]
        - required: [authResult]
    TrafficDescriptorComponents:
      description: Traffic descriptor components for the requested URSP.
      type: object
      properties:
        appDescs:
          type: object
          additionalProperties:
            $ref: 'TS29522_5GLANParameterProvision.yaml#/components/schemas/AppDescriptor'
          minProperties: 1
          description: Describes the operation systems and the corresponding applications for each
            operation systems. The key of map is osId.
        flowDescs:
          type: array
          items:
            type: string
          minItems: 1
          description: Represents a 3-tuple with protocol, server ip and server port for UL/DL
            application traffic. The content of the string has the same encoding as the IPFilterRule
            AVP value as defined in IETF RFC 6733.
        domainDescs:
          type: array
          items:
            type: string
          minItems: 1
          description: FQDN(s) or a regular expression which are used as a domain name matching
            criteria.
        ethFlowDescs:
          type: array
          items:
            $ref: 'TS29514_Npcf_PolicyAuthorization.yaml#/components/schemas/EthFlowDescription'
          minItems: 1
          description: Descriptor(s) for destination information of non-IP traffic in which only
            ethernet flow description is defined.
        dnns:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
          minItems: 1
          description: This is matched against the DNN information provided by the application.
        connCaps:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionCapabilities'
          minItems: 1
          description: This is matched against the information provided by a UE application when it
            requests a network connection with certain capabilities.
      anyOf:
        - required: [appDescs]
        - required: [flowDescs]
        - required: [domainDescs]
        - required: [ethFlowDescs]
        - required: [dnns]
        - required: [connCaps]
    AuthorizationResult:
      anyOf:
      - type: string
        enum:
          - AUTH_REVOKED
      - type: string
        description: >
          This string indicates NEF notify the AF about the service parameters authorization
          updates result.
      description: |
        Possible values are:
        - AUTH_REVOKED: Indicated the service parameters authorization is revoked.
    EventInfo:
      description: Indicates the event information.
      type: object
      properties:
        failureCause:
          $ref: '#/components/schemas/Failure'
    Failure:
      oneOf:
      - type: string
        enum:
          - UNSPECIFIED
          - UE_NOT_REACHABLE
          - UNKNOWN
          - UE_TEMP_UNREACHABLE
      - type: string
        description: >
          This string represents the failure reason for the unsuccessful result. May be
          present if the reported reportEvent attribute is "UNSUCCESS_UE_POL_DEL_SP".
      description: |
        Possible values are:
        - UNSPECIFIED: Indicates the PCF received the UE sent UE policy delivery service cause #111
          (Protocol error, unspecified).
        - UE_NOT_REACHABLE: Indicates the PCF received the notification from the AMF that the UE is
          not reachable.
        - UNKNOWN: Indicates unknown reasons upon no response from the UE, e.g. UPDS message type is
          not defined or not implemented by the UE, or not compatible with the UPDS state, in which
          the UE shall ignore the UPDS message.
        - UE_TEMP_UNREACHABLE: Indicates the PCF received the notification from the AMF that the UE
          is not reachable but the PCF will retry again.
    ConnectionCapabilities:
      anyOf:
      - type: string
        enum:
          - IMS
          - MMS
          - SUPL
          - INTERNET
      - 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
          - IMS: Indicates the connection capability to support IMS service.
          - MMS: Indicates the connection capability to support MMS service.
          - SUPL: Indicates the connection capability to support SUPL service.
          - INTERNET: Indicates the connection capability to support Internet service.
