openapi: 3.0.0

info:
  title: 3gpp-pdtq-policy-negotiation
  version: 1.1.0
  description: |
    API for PDTQ Policy Negotiation.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.522 V19.5.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-pdtq-policy-negotiation/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
        description: Represents the identifier of the AF.
        in: path
        required: true
        schema:
          type: string

    get:
      summary: Retrieve all the active PDTQ Policy Subscriptions managed by the NEF.
      operationId: GetPDTQPolicySubscs
      tags:
        - PDTQ Policy Subscriptions (Collection)
      responses:
        '200':
          description: >
            OK. All the Individual PDTQ Policy Subscription resource(s) managed by the NEF are
            returned.
            If there are no active Individual PDTQ Policy Subscription resources at the NEF, an
            empty array is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pdtq'
                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: Create a new PDTQ Policy Subscription.
      operationId: CreatePDTQPolicySubsc
      tags:
        - PDTQ Policy Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pdtq'
      responses:
        '201':
          description: >
            Created. A representation of the created Individual PDTQ Policy Subscription resource is
            returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pdtq'
          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:
        PDTQWarningNotification:
          '{$request.body#/notifUri}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/PdtqNotification'
              responses:
                '204':
                  description: >
                    No Content. The notification is successfully received and acknowledged.
                '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
        description: Represents the identifier of the AF.
        in: path
        required: true
        schema:
          type: string
      - name: subscriptionId
        description: >
          Represents the identifier of the Individual PDTQ Policy Subscription resource.
        in: path
        required: true
        schema:
          type: string

    get:
      summary: Retrieve an existing Individual PDTQ Policy Subscription resource at the NEF.
      operationId: GetIndPDTQPolicySubsc
      tags:
        - Individual PDTQ Policy Subscription (Document)
      responses:
        '200':
          description: >
            OK. The requested Individual PDTQ Policy Subscription resource is successfully
            returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pdtq'
        '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'

    patch:
      summary: Request the modification of an existing Individual PDTQ Policy Subscription resource.
      operationId: ModifyIndPDTQPolicySubsc
      tags:
        - Individual PDTQ Policy Subscription (Document)
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/PdtqPatch'
      responses:
        '200':
          description: >
            OK. The Individual PDTQ Policy Subscription resource is successfully modified and a
            representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pdtq'
        '204':
          description: >
            No Content. The Individual PDTQ Policy Subscription resource is successfully updated
            and no content is returned in the response 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'

    delete:
      summary: Request the deletion of an existing Individual PDTQ Policy Subscription resource.
      operationId: DeleteIndPDTQPolicy
      tags:
        - Individual PDTQ Policy Subscription (Document)
      responses:
        '204':
          description: >
            No Content. The Individual PDTQ Policy Subscription resource is successfully deleted.
        '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:

    Pdtq:
      description: Represents a PDTQ Policy Subscription.
      type: object
      properties:
        altQosParamSets:
          type: array
          items:
            $ref: 'TS29543_Npcf_PDTQPolicyControl.yaml#/components/schemas/AltQosParamSet'
          minItems: 1
          description: >
            Contains the alternative QoS requirements as a list of individual QoS parameters
            sets in a prioritized order.
        altQosRefs:
          type: array
          items:
            type: string
          minItems: 1
          description: >
            Contains the alternative QoS requirements as a list of QoS References in a
            prioritized order.
        appId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        aspId:
          description: Contains the identifier of the application service provider.
          type: string
        desTimeInts:
          type: array
          items:
            $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
          minItems: 1
          description: Contains the time interval(s).
        locationArea5G:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/LocationArea5G'
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        numberOfUEs:
          type: integer
          description: Contains the number of UEs.
        pdtqPolicies:
          type: array
          items:
            $ref: 'TS29543_Npcf_PDTQPolicyControl.yaml#/components/schemas/PdtqPolicy'
          minItems: 1
          description: Contains the PDTQ policies.
        qosParamSet:
          $ref: 'TS29543_Npcf_PDTQPolicyControl.yaml#/components/schemas/QosParameterSet'
        qosReference:
          type: string
          description: >
            Contains the requested QoS requirements expressed as a QoS Reference.
        referenceId:
          $ref: 'TS29543_Npcf_PDTQPolicyControl.yaml#/components/schemas/PdtqReferenceId'
        selectedPolicy:
          type: integer
          description: >
            Contains the identifier of the selected PDTQ policy.
            This attribute shall not be present during resource creation, it may be provided only in
            a subsequent resource update.
        warnNotifEnabled:
          type: boolean
          description: >
            Indicates whether the PDTQ warning notification is enabled (true) or not (false).
            Default value is false when this attribute is omitted.
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - aspId
        - desTimeInts
        - numberOfUEs
      oneOf:
        - required: [qosReference]
        - required: [qosParamSet]

    PdtqPatch:
      description: Represents the requested modification to a PDTQ Policy Subscription.
      type: object
      properties:
        selectedPolicy:
          type: integer
          description: Contains the Identifier of the selected PDTQ policy.
        warnNotifEnabled:
          type: boolean
          description: >
            Indicates whether the PDTQ warning notification is enabled (true) or not (false).
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'

    PdtqNotification:
      description: Represents a PDTQ Warning Notification.
      type: object
      properties:
        pdtqRefId:
          $ref: 'TS29543_Npcf_PDTQPolicyControl.yaml#/components/schemas/PdtqReferenceId'
        candPolicies:
          type: array
          items:
            $ref: 'TS29543_Npcf_PDTQPolicyControl.yaml#/components/schemas/PdtqPolicy'
          minItems: 1
          description: >
            Contains a list of the candidate PDTQ policies from which the AF may select
            a new PDTQ policy due to network performance or DN performance degradation.
      required:
        - pdtqRefId
        - candPolicies