openapi: 3.2.0 info: title: 3GPP Plan Provisioning Management Validation 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. 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 tags: - name: Validation Management paths: /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 responses: '200': description: List of plan validation 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-validation-jobs/{id}: parameters: - in: path name: id schema: type: string description: Unique identifier of the plan validation job. example: Dublin-plan-validation-001 required: true get: tags: - Validation Management summary: Get plan validation job details by ID description: Retrieve detailed information about a specific plan validation job using its unique identifier. operationId: getValidationJobById responses: '200': description: Job details retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/ValidationJob' '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: - Validation Management summary: Delete a plan validation job by ID description: Deletes a specific plan validation job, typically if it's not in a terminal state (e.g., running, completed, failed). operationId: deleteValidationJobById responses: '204': description: Job deleted successfully. No content is returned. '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' patch: tags: - Validation Management summary: Cancel the validation job description: Cancel the validation job operationId: cancelValidationJobById requestBody: required: true content: application/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-validation-jobs/{id}/status: get: tags: - Validation Management summary: Get job status description: Retrieve the current status of a specific plan validation job using its unique identifier. operationId: getValidationJobStatus parameters: - in: path name: id schema: type: string description: Unique identifier of the plan validation job. example: Dublin-plan-validation-001 required: true responses: '200': description: Job status retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/ValidationJobStatus' '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-validation-jobs/{id}/validation-details: get: tags: - Validation Management summary: Get validation details description: Retrieve detailed information about the validation results of a job operationId: getValidationDetails parameters: - in: path name: id schema: type: string description: Unique identifier of the plan validation job. example: Dublin-South-plan-validation-001 required: true - name: details in: query description: Selects the level of details to return. schema: type: string enum: - summary - all default: all responses: '200': description: Validation 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' components: schemas: Member: type: object description: "Defines a member identified by EITHER a single Plan Configuration Descriptor ID \nOR a Plan Configuration Group Descriptor ID, but not both.\n" oneOf: - type: object required: - planConfigDescrId properties: planConfigDescrId: type: string description: Unique id of the plan configuration descriptor. example: pcd-001 - type: object required: - planConfigGroupDescrId properties: planConfigGroupDescrId: type: string description: Unique id of the plan configuration group descriptor. example: pgc-001 ValidationJobBaseProperties: type: object properties: name: type: string description: Name of the validation job example: Dublin East Cell Deployment description: type: string description: Human-readable description of the job example: Optimize the Dublin area network mnsConsumerId: type: array description: The consumer that created and/or started the job. It may indicated a human user and/or one or more applications initiating the job. E.g. ["userid:janedoe", "appid:12314"] items: type: string validationMode: type: string enum: - CONTINUE_ON_ERROR - STOP_ON_ERROR default: CONTINUE_ON_ERROR description: Specifies the execution behavior when the plan is activated oneOf: - $ref: '#/components/schemas/PlanRef' - $ref: '#/components/schemas/PlanGroupRef' - $ref: '#/components/schemas/EmbeddedPlan' - $ref: '#/components/schemas/EmbeddedPlanGroup' - $ref: '#/components/schemas/FallbackPlanRef' example: name: 5G-Dublin-East-Rollout description: Optimize the 5G network in Dublin East planConfigDescr: activationMode: ATOMIC customProperties: technology-type: NR location: Dublin configChangesContentType: YANG_BASED configChanges: - modifyOperator: merge changeId: Dublin-Center_DC-01_555777999 target: /SubNetwork=Dublin-Center/ManagedElement=DC-001/NRCellDU=1 value: ssbDuration: 2 additionalProperties: true PlanConfigurationGroupDescriptor: type: object required: - members properties: id: type: string description: Unique id of the plan group configuration descriptor example: plan-001 name: type: string description: Descriptive name of the plan group configuration descriptor example: Rollout-5G-Dublin-East version: type: string description: version of the plan group configuration descriptor example: 1.0.0 description: type: string description: Used to describe the purpose of the plan group configuration example: This is the plan for the new 5G rollout in Dublin east. customProperties: type: object description: A dynamic set of custom properties provided by client additionalProperties: true example: technology-type: NR location: Dublin isOrdered: type: boolean description: Specifies if the members of the planned configuration group are ordered. When ordered, the planned configuration group members shall be validated/activated in the specified order. When not ordered the planned configuration group members can be validated/activated in any order default: false isFailOnMemberConflicts: type: boolean description: Specifies if the activation shall fail on detection of conflicts between planned configuration group members, or if the operations shall be processed as if there were no conflicts default: false activationMode: type: string enum: - ATOMIC - BEST_EFFORT - STOP_ON_ERROR default: BEST_EFFORT description: Specifies the execution behavior when the plan configuration group is activated example: BEST_EFFORT validationState: type: string enum: - NOT_VALIDATED - PARTIALLY_VALID - VALID - INVALID default: NOT_VALIDATED description: The validation state for the last time plan configuration group was validated example: NOT_VALIDATED lastModifiedAt: type: string format: date-time description: the last time the plan was modified example: '2025-03-06T16:50:26-08:00' lastValidatedAt: type: string format: date-time description: last time the plan was validated example: '2025-03-06T16:50:29-08:00' members: type: array description: list of plan or plan group descriptor identifiers items: $ref: '#/components/schemas/Member' example: - planConfigDescrId: pcd-network-101 - planConfigGroupDescrId: pgc-europe-east-group - planConfigDescrId: pcd-radio-tuning-005 - planConfigGroupDescrId: pgc-5g-core-rollout ConfigChangeWritable: type: object properties: modifyOperator: type: string enum: - create - merge - merge-create - delete description: The operation to perform example: create description: type: string description: text describing the change example: modify NR cell for optimisation target: type: string description: Target data node path example: /_3gpp-common-subnetwork:SubNetwork=Irl/3gpp-common-mecontext:MeContext=Dublin-1/_3gpp_nrm_managedelement:ManagedElement=1/_3gpp_nrm_nrcelldu:NRCellDU=4 changeId: description: The identifier of the operation. It may or may not be provided If provided, it shall be unique within an instance of "configChanges" and it shall be provided for all changes in "configChanges". example: cell-operation-001 value: type: object additionalProperties: true description: Value to apply (for create/merge/merge-create operations) additionalProperties: true required: - modifyOperator - target EmbeddedPlanGroup: type: object required: - planConfigGroupDescr properties: planConfigGroupDescr: $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' ValidationJobStatus: type: object required: - jobState - validationState properties: jobState: allOf: - $ref: '#/components/schemas/JobState' example: COMPLETED validationState: allOf: - $ref: '#/components/schemas/ValidationState' example: NOT_VALIDATED startedAt: type: string format: date-time example: '2024-12-02T13:16:54.088Z' stoppedAt: type: string format: date-time example: '2024-12-02T13:16:58.088Z' ConfigChangesContentType: type: string description: The supported configuration content types. enum: - YANG_BASED - OPENAPI_BASED default: YANG_BASED ValidationJobLinks: allOf: - type: object properties: self: allOf: - $ref: '#/components/schemas/LinkObject' - type: object properties: href: type: string default: '{apiRoot}/plan-management/v1/plan-validation-jobs/{validationJobId}' title: type: string enum: - Link to the plan validation job method: type: string enum: - GET example: href: '{apiRoot}/plan-management/v1/plan-validation-jobs/val-job-001' title: Link to the plan validation job type: application/json templated: true method: GET descriptor: description: A URI reference to the plan (or plan group) configuration descriptor allOf: - $ref: '#/components/schemas/LinkObject' - type: object properties: href: type: string example: '{apiRoot}/plan-management/v1/plan-descriptors/{id}' title: type: string enum: - Link to the plan (or plan group) configuration descriptor method: type: string enum: - GET example: href: '{apiRoot}/plan-management/v1/plan-descriptors/plan-descriptor-001' title: Link reference to the plan (or plan group) configuration descriptor type: application/json templated: true method: GET status: allOf: - $ref: '#/components/schemas/LinkObject' - type: object properties: href: type: string default: '{apiRoot}/plan-management/v1/plan-validation-jobs/{id}/status' title: type: string enum: - Link to GET the job status method: type: string enum: - GET description: A URI reference to the status information example: href: '{apiRoot}/plan-management/v1/plan-validation-jobs/myjob-111/status' title: Link to GET the job status type: application/json templated: true method: GET validationDetails: allOf: - $ref: '#/components/schemas/LinkObject' - type: object properties: href: type: string default: '{apiRoot}/plan-management/v1/plan-validation-jobs/{id}/activation-details' title: type: string enum: - Link to GET the job details method: type: string enum: - GET description: A URI reference to the status information example: href: '{apiRoot}/plan-management/v1/plan-validation-jobs/myjob-111/status' title: Link to GET the job status type: application/json templated: true method: GET cancel: allOf: - $ref: '#/components/schemas/LinkObject' - type: object properties: href: type: string default: '{apiRoot}/plan-management/v1/plan-validation-jobs/{id}' title: type: string enum: - Link to cancel the job method: type: string enum: - PATCH description: A URI reference to cancel the job example: href: '{apiRoot}/plan-management/v1/plan-validation-jobs/myjob-111' title: Link to cancel the job type: application/json templated: true method: PATCH additionalProperties: $ref: '#/components/schemas/LinkObject' required: - self - descriptor - status - validationDetails - cancel PlanGroupRef: type: object required: - planConfigGroupDescrId properties: planConfigGroupDescrId: type: string LinkObject: type: object description: Defines the structure of a single hypermedia link. properties: href: type: string format: uri-reference description: The target URI of the link. templated: type: boolean description: Indicates if the href is a URI Template (RFC 6570). default: true type: type: string description: The content type expected when following this link (MIME type). title: type: string description: A human-readable title that describes the link's purpose. method: type: string enum: - GET - POST - PUT - DELETE - PATCH description: The HTTP method to use for this action link. required: - href SummaryStatus: type: object properties: notFinished: type: integer example: 1 succeeded: type: integer example: 3 failed: type: integer example: 3 rollbackSucceeded: type: integer example: 0 rollbackFailed: type: integer example: 0 conflicting: type: integer example: 0 PlanConfigurationDescriptorBaseProperties: type: object properties: name: type: string description: Descriptive name of the plan group configuration descriptor example: Rollout-5G-Dublin-East version: type: string description: The version of the planned configuration. Its format is implementation specific. example: 1.0.0 description: type: string description: Used to describe the purpose of the plan configuration example: This is the plan for the new 5G rollout in Dublin east. customProperties: type: object description: A dynamic set of custom properties provided by client additionalProperties: true example: technology-type: NR location: Dublin configChangesContentType: $ref: '#/components/schemas/ConfigChangesContentType' activationMode: type: string enum: - ATOMIC - BEST_EFFORT - STOP_ON_ERROR default: BEST_EFFORT description: Specifies the execution behavior when the plan is activated example: BEST_EFFORT ValidationState: type: string enum: - UNKNOWN - VALIDATION_SUCCEEDED - VALIDATION_FAILED example: VALIDATION_SUCCEEDED ErrorDetail: type: object properties: title: type: string description: A short, human-readable summary of the problem type example: Data already exists; cannot be created type: type: string description: The type of the error enum: - SCHEMA_VALIDATION_ERROR - DATA_NODE_TREE_ERROR - MODIFICATION_NOT_ALLOWED - ACCESS_CONTROL_CONFLICT - APPLICATION_LAYER_ERROR - SERVER_ERROR - OTHER reason: type: string enum: - NEW_DATA_NODE_NAME_INVALID - NEW_DATA_NODE_VALUE_INVALID - NEW_DATA_NODE_CONTAINMENT_INVALID - FINAL_DATA_NODE_VALUE_INVALID - FINAL_DATA_NODE_UNIQUENESS_INVALID - FINAL_DATA_NODE_MULTIPLICITY_INVALID - FINAL_DATA_NODE_CARDINALITY_INVALID - TARGET_DATA_NODE_NOT_FOUND - TARGET_DATA_NODE_PARENT_NOT_FOUND - TARGET_DATA_NODE_FOUND - TARGET_DATA_NODE_NOT_WRITABLE - TARGET_DATA_NODE_INVARIANT - TARGET_DATA_NODE_CREATION_NOT_ALLOWED - TARGET_DATA_NODE_DELETION_NOT_ALLOWED - ACCESS_DENIED - OTHER example: NEW_DATA_NODE_CONTAINMENT_INVALID detail: type: string description: A human-readable explanation specific to this occurrence of the problem. example: NRCellDU=1234 already exists in the network badDataNode: type: string example: /_3gpp-common-subnetwork:SubNetwork=Irl/_3gpp-common-mecontext:MeContext=Dublin-1 errorInfo: type: object description: additional error info (e.g. stackdump) additionalProperties: true required: - type - badDataNode FallbackPlanRef: type: object required: - fallbackConfigDescrId properties: fallbackConfigDescrId: type: string JobState: type: string enum: - NOT_STARTED - QUEUED - RUNNING - CANCELLING - CANCELLED - COMPLETED - FAILED default: NOT_STARTED example: COMPLETED ExecutionDetails: type: object description: Details of the execution of the operations that are contained in the planned configuration or planned configuration group referenced in the job. properties: summary: $ref: '#/components/schemas/SummaryStatus' results: type: array items: $ref: '#/components/schemas/Result' memberConflicts: type: array items: $ref: '#/components/schemas/MemberConflict' example: summary: notFinished: 0 succeeded: 1 failed: 0 rollbackSucceeded: 0 rollbackFailed: 0 conflicting: 0 results: [] memberConflicts: [] EmbeddedPlan: type: object required: - planConfigDescr properties: planConfigDescr: $ref: '#/components/schemas/PlanConfigurationDescriptorRequest' MemberConflict: type: object properties: memberConflict: type: array items: $ref: '#/components/schemas/MemberOp' PlanRef: type: object required: - planConfigDescrId properties: planConfigDescrId: type: string PlanConfigurationDescriptorRequest: allOf: - $ref: '#/components/schemas/PlanConfigurationDescriptorBaseProperties' - type: object required: - configChanges properties: configChanges: description: The plan configuration changes type: array items: $ref: '#/components/schemas/ConfigChangeWritable' CancelRequest: type: object properties: cancelRequest: type: boolean description: Must be set to true to initiate cancellation. enum: - true required: - cancelRequest additionalProperties: false ValidationJob: allOf: - $ref: '#/components/schemas/ValidationJobBaseProperties' - $ref: '#/components/schemas/ValidationJobStatus' - type: object properties: id: type: string description: id of the validation job example: job-id-3985199134 currentConfigTime: type: string format: date-time description: The date and time of the current configuration state against which the planned configuration or planned configuration group is validated. cancelRequest: type: boolean description: boolean indicating the request of a job cancellation default: false example: true jobDetails: $ref: '#/components/schemas/JobDetails' validationDetails: $ref: '#/components/schemas/ExecutionDetails' _links: $ref: '#/components/schemas/ValidationJobLinks' required: - id - jobState - jobDetails - cancelRequest - validationMode - validationState - validationDetails - _links MemberOp: type: object description: The identification of two or more operation members that have a conflict. properties: planConfigDescrId: type: string description: The plan configuration descriptor Id. target: description: The path of the target change resource. type: string required: - planConfigDescrId - target oneOf: - required: - changeId properties: changeId: type: string description: The identifier of the operation. It may or may not be provided If provided, it shall be unique within an instance of "configChanges" and it shall be provided for all changes in "configChanges". example: change-cell-001-1 - required: - changeIndex properties: changeIndex: type: integer description: The identification of the operation. It is the positional index of the operation in the operation set ("changeIndex"). The positional index of the leftmost element is "0". Exactly one of "changeId" or "changeIndex" shall be provided. example: 0 JobListEntry: allOf: - type: object properties: id: type: string description: id of the job. example: plan-job-1 name: type: string description: name of the job. example: Dublin East Rollout Job description: type: string description: description/purpose of the job. example: Job to do dublin east rollout jobState: $ref: '#/components/schemas/JobState' required: - id - jobState JobDetails: properties: message: type: string errors: type: array items: $ref: '#/components/schemas/ErrorDetail' additionalProperties: true Result: type: object description: Details of the execution of the operations that are contained in the planned configuration. properties: planConfigDescrId: type: string description: If planned configuration groups are activated, this information elements specifies the planned configuration descriptor identifier, for which error details are reported. If a planned configuration is activated or validated, this information element is absent. example: descriptor-001 state: type: string enum: - NOT_STARTED - PROCESSING - SUCCEEDED - FAILED default: NOT_STARTED description: The state of the operation activation. example: SUCCEEDED target: type: string example: /SubNetwork=1/MeContext=2/ManagedElement=3 errors: type: array items: $ref: '#/components/schemas/ErrorDetail' required: - target - state oneOf: - required: - changeId properties: changeId: type: string description: The identifier of the operation. It may or may not be provided If provided, it shall be unique within an instance of "configChanges" and it shall be provided for all changes in "configChanges". example: change-cell-001-1 - required: - changeIndex properties: changeIndex: type: integer description: The identification of the operation. It is the positional index of the operation in the operation set ("changeIndex"). The positional index of the leftmost element is "0". Exactly one of "changeId" or "changeIndex" shall be provided. example: 0 example: changeId: changeId-002-update-config target: /SubNetwork=1/MeContext=2/ManagedElement=3 state: FAILED errors: - type: VALIDATION_ERROR title: Validation Error reason: VALUE_INVALID detail: The provided value 'some-value' for 'someAttr' is not allowed. Valid values are 'some-value-x', 'some-value-y'. path: /SubNetwork=1/MeContext=2/ManagedElement=3/attributes/someAttr errorInfo: attributeName: someAttr invalidValue: some-value ValidationJobRequest: allOf: - $ref: '#/components/schemas/ValidationJobBaseProperties' example: name: 5G-Dublin-East-Rollout description: Optimize the 5G network in Dublin East planConfigDescr: activationMode: ATOMIC customProperties: technology-type: NR location: Dublin configChangesContentType: YANG_BASED configChanges: - modifyOperator: merge changeId: Dublin-Center_DC-01_555777999 target: /SubNetwork=Dublin-Center/ManagedElement=DC-001/NRCellDU=1 value: ssbDuration: 2 externalDocs: description: 3GPP TS 28.572; Generic management services url: http://www.3gpp.org/ftp/Specs/archive/28_series/28.572/