3GPP TS 28.572 Plan Management API

openapi: 3.0.1
info:
  title: 3GPP Plan Provisioning Management API
  version: 19.2.0
  description: >-
    OAS 3.0.1 specification of API for managing network configuration plans and related jobs
    © 2026, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.
externalDocs:
  description: 3GPP TS 28.572; Generic management services
  url: http://www.3gpp.org/ftp/Specs/archive/28_series/28.572/
servers:
  - url: '{MnSRoot}/plan-management/{MnSVersion}'
    variables:
      MnSRoot:
        description: See clause 4.4.2 of TS 32.158
        default: http://example.com/cm
      MnSVersion:
        description: Version number of the OpenAPI definition
        default: v1

# Note the examples are demonstrative only and may not all contain all required attributes for the given MO types.
paths:
  /plan-descriptors:
    post:
      tags:
        - Plan Descriptor Management 
      summary: Create a new plan descriptor
      description: Creates a new configuration plan descriptor that can be later activated.
      operationId: createPlanDescriptor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanConfigurationDescriptorRequest'
            example:
              name: "Rollout-5G-Dublin-East"
              version: "1.0.0"
              description: "This is the plan for the new 5G rollout in Dublin east."
              customProperties:
                technology-type: "NR"
                location: "Dublin"
              configChangesContentType: YANG_BASED
              configChanges:
                - modifyOperator: "create"
                  changeId: "add-nr-cell-001"
                  description: "Add new NR cell for initial deployment in Dublin-4 area."
                  target: "/SubNetwork=Irl/MeContext=Dublin-1/ManagedElement=1/GNBDUFunction=1"
                  value:
                    NRCellDU:
                      - id: '4'
                        attributes:
                          userLabel: "Dublin-1-Cell-4"
                          ssbDuration: 2
      responses:
        '201':
          description: Plan descriptor created successfully 
          headers:
            Location:
              description: URI of the created plan descriptor.
              schema:
                type: string
                format: uri-reference  
                example: "/plan-descriptors/my-plan11"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanConfigurationDescriptorResponse' 
        '400':
          description: Invalid request parameters or malformed input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '409': 
          description: A plan descriptor with the given ID already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

    get:
      tags:
        - Plan Descriptor Management 
      summary: Get plan configuration descriptors 
      description: Retrieve a list of  existing plan descriptors.
      operationId: getPlanDescriptors 
      responses:
        '200':  
          description: List of the plan configuration descriptors retrieved successfully.
          content:
            application/json:
              schema:
                type: array 
                items:
                  $ref: '#/components/schemas/DescriptorListEntry'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /plan-descriptors/{id}:  
    parameters: 
      - in: path
        name: id
        schema:
          type: string
          description: Unique identifier of the plan descriptor.
          example: "NewNetworkElement10-group-plan-001"
        required: true 

    get: 
      tags:
        - Plan Descriptor Management
      summary: Get a specific plan descriptor by ID
      description: Retrieve the details of a single plan descriptor using its unique identifier.
      operationId: getPlanDescriptorById
      responses:
        '200':
          description: Plan descriptor retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanConfigurationDescriptorResponse' 
        '404': 
          description: Plan descriptor does not exist
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    put:
      tags:
        - Plan Descriptor Management 
      summary: Replace a plan descriptor
      description: Replace a configuration plan descriptor
      operationId: putPlanDescriptor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanConfigurationDescriptorRequest'
            example:
              {
                "name": "Rollout-5G-Dublin-East",
                "description": "This is the plan for the new 5G rollout in Dublin east.",
                "customProperties": {
                  "technology-type": "NR",
                  "location": "Dublin"
                },
                "configChanges": [
                  {
                    "modifyOperator": "merge",
                    "changeId": "Dublin-Center_DC-01_555777999",
                    "target": "/SubNetwork=Dublin-Center/ManagedElement=DC-001/NRCellDU=1",
                    "value": {
                          "ssbDuration": 2
                    }
                  }
                ]
              } 
      responses:
        '204':
          description: Plan descriptor replaced successfully. No content is returned
        '400':
          description: Invalid request parameters or malformed input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':  
          description: Plan descriptor not found. 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
                
    delete:
      tags:
        - Plan Descriptor Management
      summary: Delete a plan descriptor by ID
      description: Deletes a specific configuration plan descriptor using its unique identifier
      operationId: deletePlanDescriptorById
      responses:
        '204': 
          description: Plan descriptor deleted successfully.
        '404':
          description: Plan descriptor not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'  ##EDITOR The example in swagger is very strange. The example cannot be the same for put and delete. TODO LATER
        '409': 
          description: Conflict - The plan descriptor cannot be deleted due to its current state or dependencies (For example, it is referenced in a plan group descriptor). 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /plan-group-descriptors:
    post:
      tags:
        - Plan Group Descriptor Management 
      summary: Create a new plan group descriptor
      description: Creates a new configuration plan group descriptor that can be later activated.
      operationId: createPlanGroupDescriptor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanConfigurationGroupDescriptor'

      responses:
        '201':
          description: Plan group descriptor created successfully 
          headers:
            Location:
              description: URI of the created plan descriptor.
              schema:
                type: string
                format: uri-reference  
                example: "/plan-group-descriptors/mygroup-11"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanConfigurationGroupDescriptorResponse' 
        '400':
          description: Invalid request parameters or malformed input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail' 
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

    get:
      tags:
        - Plan Group Descriptor Management 
      summary: Get plan configuration descriptors
      description: Retrieve a list of existing plan descriptors.
      operationId: getPlanGroupDescriptors 
      responses:
        '200':  
          description: List of the plan configuration descriptors retrieved successfully.
          content:
            application/json:
              schema:
                type: array 
                items: 
                  $ref: '#/components/schemas/DescriptorListEntry'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /plan-group-descriptors/{id}:  
    parameters: 
      - in: path
        name: id
        schema:
          type: string
          description: Unique identifier of the plan group descriptor.
          example: "NewNetworkElement10-group-plan-001"
        required: true 

    get: 
      tags:
        - Plan Group Descriptor Management
      summary: Get a specific plan group descriptor by ID
      description: Retrieve the details of a plan group descriptor using its unique identifier.
      operationId: getPlanGroupDescriptorById
      responses:
        '200':
          description: Plan group descriptor retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanConfigurationGroupDescriptorResponse' 
        '404': 
          description: Plan group descriptor does not exist
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    put:
      tags:
        - Plan Group Descriptor Management 
      summary: Replace a plan group descriptor
      description: Replace a configuration plan group descriptor
      operationId: putPlanGroupDescriptor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanConfigurationGroupDescriptor'
      responses:
        '200':
          description: Plan group descriptor replaced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanConfigurationGroupDescriptorResponse' 
        '400': 
          description: Invalid request parameters or malformed input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':   
          description: Plan group descriptor not found. 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
                
    delete:
      tags:
        - Plan Group Descriptor Management
      summary: Delete a plan group descriptor by ID
      description: Deletes a plan group descriptor using its unique identifier
      operationId: deletePlanGroupDescriptorById
      responses:
        '204': 
          description: Plan descriptor deleted successfully.
        '404':
          description: Plan descriptor not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '409':  
          description: The plan group descriptor cannot be deleted due to its current state or dependencies (For example, it is referenced in a plan group descriptor).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
   
  /fallback-descriptors:
    get:
      tags:
        - Fallback Descriptor Management 
      summary: Get fallback configuration descriptors 
      description: Retrieve a list of  existing fallback descriptors.
      operationId: getFallbackDescriptors 
      responses:
        '200':  
          description: List of the fallback configuration descriptors retrieved successfully.
          content:
            application/json:
              schema:
                type: array 
                items: 
                  $ref: '#/components/schemas/DescriptorListEntry'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /fallback-descriptors/{id}:
    parameters: 
      - in: path
        name: id
        schema:
          type: string
          description: Unique identifier of the fallback descriptor.
          example: "Fallback-Dublin-plan-001"
        required: true 
    get: 
      tags:
        - Fallback Descriptor Management
      summary: Get a specific fallback descriptor by ID
      description: Retrieve the details of a single fallback descriptor using its unique identifier.
      operationId: getFallbackDescriptorById
      responses:
        '200':
          description: Fallback Plan descriptor retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FallbackConfigurationDescriptorResponse'
        '404': 
          description: Fallback descriptor does not exist
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    delete:
      tags:
        - Fallback Descriptor Management
      summary: Delete a Fallback descriptor by ID
      description: Deletes a specific fallback plan descriptor using its unique identifier
      operationId: deleteFallbackDescriptorById
      responses:
        '204': 
          description: Fallback descriptor deleted successfully.
        '404':
          description: Fallback descriptor not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'  ##EDITOR The example in swagger is very strange. The example cannot be the same for put and delete. TODO LATER
        '409': 
          description: Conflict - The fallback descriptor cannot be deleted due to its current state. 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /trigger-descriptors:
    post:
      tags:
        - Trigger Descriptor Management 
      summary: Create a new trigger descriptor
      description: Creates a new trigger descriptor
      operationId: createTriggerDescriptor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerDescriptorRequest'
 
      responses:
        '201':
          description: Trigger descriptor created successfully 
          headers:
            Location:
              description: URI of the created trigger descriptor.
              schema:
                type: string
                format: uri-reference
                example: "/trigger-descriptors/mytrigger-11"  
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerDescriptorResponse' 
        '400':
          description: Invalid request parameters or malformed input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail' 
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

    get:
      tags:
        - Trigger Descriptor Management 
      summary: Get trigger descriptors
      description: Retrieve a list of existing trigger descriptors.
      operationId: getTriggerDescriptors 
      responses:
        '200':
          description: List of the trigger descriptors retrieved successfully.
          content:
            application/json:
              schema:
                type:  array
                items: 
                  $ref: '#/components/schemas/DescriptorListEntry'

  /trigger-descriptors/{id}:  
    parameters: 
      - in: path
        name: id
        schema:
          type: string
          description: Unique identifier of the  descriptor.
          example: "NewNetworkElement10-trigger-001"
        required: true 

    get: 
      tags:
        - Trigger Descriptor Management
      summary: Get a specific trigger descriptor by ID
      description: Retrieve the details of a single descriptor using its unique identifier.
      operationId: getTriggerDescriptorById
      responses:
        '200':
          description: Trigger descriptor retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerDescriptorResponse'
        '404': 
          description: Trigger descriptor not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    put:
      tags:
        - Trigger Descriptor Management 
      summary: Replace a trigger descriptor  
      description: Replace a trigger descriptor
      operationId: putTriggerDescriptor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerDescriptorRequest'
      responses:
        '204':  
          description: Trigger descriptor created successfully  
        '400':
          description: Invalid request parameters or malformed input.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':  
          description: Trigger descriptor not found 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
                
    delete:
      tags:
        - Trigger Descriptor Management
      summary: Delete a trigger descriptor by ID
      description: Deletes a specific trigger descriptor using its unique identifier
      operationId: deleteTriggerDescriptorById
      responses:
        '204': 
          description: Trigger descriptor deleted successfully.
        '404':
          description: Trigger descriptor not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail' 
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
                        
  /plan-activation-jobs:
    post:
      tags:
        - Activation Management
      summary: Create a new plan activation job  
      description: Creates and starts a new plan activation job based on an existing plan descriptor (or plan group descriptor or fallback descriptor).  The new job's ID will be generated by the server and returned in the Location header.
      operationId: createActivationJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationJobWritableProperties'
      responses:
        '201':
          description: Plan activation job created successfully.
                       The response body provides job details, and the Location header points to the new job.
          headers:
            Location:
              description: URI of the created job resource.
              schema:
                type: string
                format: uri-reference  
                example: "/plan-activation-jobs/myjob-111"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationJob'
        '400':  
          description: Invalid request payload or parameters (e.g., malformed JSON, missing required fields).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

    get:
      tags:
        - Activation Management
      summary: Get plan activation jobs
      description: Retrieve a list of plan activation jobs. 
      operationId: getActivationJobs
      parameters:
        - in: query
          name: job-state
          schema:
            $ref: '#/components/schemas/JobState'
          description: Filter jobs by their current state.
          example: "RUNNING"
      responses:
        '200':
          description: List of plan activation jobs retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobListEntry' 
        '400':  
          description: Invalid query parameters
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /plan-activation-jobs/{id}:  
    parameters:  
      - in: path
        name: id
        schema:
          type: string
          description: Unique identifier of the plan activation job.
          example: "Dublin-plan-activation-001"
        required: true 
    get:
      tags:
        - Activation Management
      summary: Get plan activation job details by ID
      description: Retrieve detailed information about a specific plan activation job using its unique identifier.
      operationId: getActivationJobById
      responses:
        '200':
          description: Job details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationJob'  
        '404':
          description: Job not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

    delete:
      tags:
        - Activation Management
      summary: Delete a plan activation job by ID
      description: Deletes a specific plan activation job, typically if it's not in a terminal state (e.g., running, completed, failed).
      operationId: deleteActivationJobById
      responses:
        '204':
          description: Job deleted successfully. No content is returned.
        '404':
          description: Job not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '409': 
          description:  Cannot delete job in its current state (e.g., already running). 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    patch:
      tags:
        - Activation Management
      summary: Cancel the activation job 
      description: Cancel the activation job
      operationId: cancelActivationJobById      
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRequest'  
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/CancelRequest'
      responses:
        '202': 
          description: Job cancel request was accepted and cancellation is ongoing 
        '204':
          description: Job cancel request was successfully completed 
        '404':
          description: Job not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '422':
          description: Semantic error - e.g. job was not in RUNNING state
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /plan-activation-jobs/{id}/status:
    get:
      tags:
        - Activation Management 
      summary: Get job status 
      description: Retrieve the current status of a specific plan activation job using its unique identifier. 
      operationId: getJobStatus 
      parameters:
        - in: path
          name: id
          schema:
            type: string
            description: Unique identifier of the plan activation job.
            example: "Dublin-plan-activation-001"
          required: true 
      responses:
        '200':
          description: Job status retrieved successfully. 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationJobStatus' 
        '404':
          description: Job not found. 
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail' 
        '500': 
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

  /plan-activation-jobs/{id}/activation-details:
    get:
      tags:
        - Activation Management
      summary: Get activation details
      description: Retrieve detailed information about the activation results of a job
      operationId: getActivationDetails
      parameters:
        - in: path
          name: id
          schema:
            type: string
            description: Unique identifier of the plan activation job.
            example: "Dublin-plan-activation-001"
          required: true 
        - name: expand
          in: query
          description: >-
            By default the activation details results shall include the FAILED operations only.  This parameter indicates whether to expand all details of the activation results to also include the 'SUCCEEDED' operations.
          required: false
          schema:
            type: string
            enum:
              - all
      responses:
        '200':
          description: Activation details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionDetails' 
        '404':
          description: Job not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'


  /plan-validation-jobs:  
    post:
      tags:
        - Validation Management
      summary: Create a new plan validation job
      description: Creates and starts a new plan validation job based on an existing plan descriptor.  The new job's ID will be generated by the server and returned in the Location header.
      operationId: createValidationJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationJobRequest'
      responses:
        '201':
          description: Plan validation job created successfully.
                       The response body provides job details, and the Location header points to the new job.
          headers:
            Location:
              description: URI of the created job resource.
              schema:
                type: string
                format: uri-reference
                example: "/plan-validation-jobs/myjob-111"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationJob'
        '400':
          description: Invalid request payload or parameters (e.g., malformed JSON, missing required fields).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'

    get:
      tags:
        - Validation Management
      summary: Get plan validation jobs
      description: Retrieve a list of plan validation jobs. 
      operationId: getValidationJobs
      parameters:
        - in: query
          name: job-state
          schema:
            $ref: '#/components/schemas/JobState' 
          description: Filter jobs by their current state.
          example: "job-state=COMPLETED" # Example state for validation jobs
      responses:
        '200':
          description: List of plan validation jobs retrieved successfully.
          content:
            application/json:
              schema:
               

# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/3gpp/refs/heads/main/openapi/3gpp-ts28572-planmanagement.yml