From 0868b4b23b39cc7401174283eead9cb8b2ed8cc1 Mon Sep 17 00:00:00 2001 From: lengyelb Date: Fri, 15 Aug 2025 16:52:13 +0200 Subject: [PATCH 1/4] Add new file TS28572_PlanManagement.yaml --- OpenAPI/TS28572_PlanManagement.yaml | 2467 +++++++++++++++++++++++++++ 1 file changed, 2467 insertions(+) create mode 100644 OpenAPI/TS28572_PlanManagement.yaml diff --git a/OpenAPI/TS28572_PlanManagement.yaml b/OpenAPI/TS28572_PlanManagement.yaml new file mode 100644 index 000000000..a9b049958 --- /dev/null +++ b/OpenAPI/TS28572_PlanManagement.yaml @@ -0,0 +1,2467 @@ +openapi: 3.0.0 ##EDITOR get, delete Fallback; FallbackConfigurationDescriptor missing +info: + title: 3GPP Plan Provisioning Management API + version: 1.0.0 + description: API for managing network configuration plans and related jobs + +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/PlanConfigurationDescriptor' + 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" + }, + "currentConfigAddress": "http://example.org/3gpp/ProvMnS/v1", + "planConfigContentType" : "application/vnd.3gpp.yang-patch+json", + "planConfig": { + ... + } + } + 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/PlanConfigurationDescriptor' + 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" + }, + "currentConfigAddress": "http://example.org/3gpp/ProvMnS/v1", + "planConfig": { + ... + } + } + responses: + '200': + description: Plan descriptor replaced successfully + content: + application/json: + schema: + $ref: '#/components/schemas/PlanConfigurationDescriptorResponse' ##EDITOR why is a return data needed? Is it not trivial ? TODO remove 200 + '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 nbe the same for put and delete. TODO + '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' + example: + { + "name": "Rollout-5G-Dublin-East", + "version" : "1.0.0", + "description": "This is the plan for the new 5G rollout in Dublin east.", + "applyMode" : "BEST_EFFORT", + "isOrdered" : true, + "isFailOnMemberConflicts" : true, + "members": [{"type" : "PLAN", "identifier" : "plan-descriptor-001"}, {"type" : "PLAN_GROUP", "identifier" : "plan-group-descriptor-001"}] + } + responses: + '200': + description: Plan group descriptor replaced successfully + content: + application/json: + schema: + $ref: '#/components/schemas/PlanConfigurationGroupDescriptorResponse' + '400': ##EDITOR should we use 422 ? + 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': ##EDITOR can you delete a plan or group that is being activated IMHO not. Add here. Can a plan/group be deleted if it is part of a validationJob? IMHJO yes + 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' + + /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/TriggerDescriptor' + + 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: Plan 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/TriggerDescriptor' + responses: + '200': ##EDITOR why do we need 200? Isnt 204 enough ? + description: Trigger descriptor replaced successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TriggerDescriptorResponse' + '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: ##EDITOR remove plan- from activation-job ActivationJob generally + post: + tags: + - Activation Management + summary: Create a new plan activation job ##EDITOR or group or fallbackdescr + description: Creates and starts a new plan activation 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: createPlanActivationJob + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PlanActivationJobRequest' + 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/PlanActivationJobResponse' + '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. ##EDITOR describe that the order of items is vendor specific, but it shall be fixed. + operationId: getPlanActivationJobs + parameters: + - in: query + name: job-state + schema: + $ref: '#/components/schemas/JobState' + description: Filter jobs by their current state. + example: "RUNNING" + - in: query + name: limit + schema: + type: integer ##EDIOR this paging is slightly broken. Prposal to remove. + format: int32 + minimum: 1 + description: Maximum number of jobs to return. + - in: query + name: offset + schema: + type: integer + format: int32 + minimum: 0 + default: 0 + description: Number of jobs to skip before starting to collect the result set. + 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: + - $ref: '#/components/parameters/jobId' + 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: getPlanActivationJobById + responses: + '200': + description: Job details retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/PlanActivationJobResponse' + '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: deletePlanActivationJobById + 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' + + /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: + - $ref: '#/components/parameters/jobId' + 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: + - $ref: '#/components/parameters/jobId' + 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-activation-jobs/{id}/status/job-state: + parameters: + - $ref: '#/components/parameters/jobId' + put: + tags: + - Activation Management + summary: Cancel the activation job by modifying the jobState property ##EDITOR harmonize with stage2 where there is a separate cancelRequest or is-cancel-requested boolean. + description: Cancel the activation job by modifying the jobState property + operationId: cancelActivationJobById + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CancelRequest' + example: + { + "jobState": "CANCELLING" + } + responses: + '200': + description: Job cancel request was successfully completed + '202': + description: Job cancel request was accepted and cancellation is ongoing + '400': + description: Bad request . + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorDetail' + '404': + description: Job not found. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorDetail' + '422': + description: Semantic error - - perhaps jobState not set to correct value. + 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: ##EDITOR remove plan- from the name, see stage2 + 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: createPlanValidationJob + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PlanValidationJobRequest' + 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/PlanValidationJobResponse' + '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: getPlanValidationJobs + parameters: + - in: query + name: job-state + schema: + $ref: '#/components/schemas/JobState' + description: Filter jobs by their current status. + example: "RUNNING" + - in: query + name: limit + schema: + type: integer ##EDITOR paging is slightly broken. Same as for activtion-jobs + format: int32 + minimum: 1 + description: Maximum number of jobs to return. + - in: query + name: offset + schema: + type: integer + format: int32 + minimum: 0 + default: 0 + description: Number of jobs to skip before starting to collect the result set. + responses: + '200': + description: List of plan validation jobs retrieved successfully. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/JobListEntry' + '500': + description: Internal server error. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorDetail' + + /plan-validation-jobs/{id}: + parameters: + - $ref: '#/components/parameters/jobId' + 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: getPlanValidationJobById + responses: + '200': + description: Job details retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/PlanValidationJobResponse' + '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: deletePlanValidationJobById + 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). ##EDITOR I think even a running valaidationjob can be deleted. Do we need this? + 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: + - $ref: '#/components/parameters/jobId' + 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: + - $ref: '#/components/parameters/jobId' + - name: expand + in: query + description: Level of detail to return + schema: + type: string + enum: [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' + + /plan-validation-jobs/{id}/status/job-state: + parameters: + - $ref: '#/components/parameters/jobId' + put: + tags: + - Validation Management + summary: Cancel the validation job by modifying the jobState property + description: Cancel the validation job by modifying the jobState property ##EDITOR harmonize cancelling with stage2 + operationId: cancelValidationJobById + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CancelRequest' + example: + { + "jobState": "CANCELLING" + } + responses: + '200': + description: Job cancel request was successfully completed + '202': + description: Job cancel request was accepted and cancellation is ongoing + '400': + description: Bad request - perhaps jobState not set to correct value. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorDetail' + '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' + +components: + parameters: + jobId: + name: id + in: path + description: Unique identifier of the job + required: true + schema: + type: string + example: "myjob-111" + descriptorId: + name: descriptorId + in: path + description: Unique identifier of the plan descriptor + required: true + schema: + type: string + example: "plan-descriptor-001" + + + schemas: + PlanConfigurationDescriptor: + type: object + required: + - planConfigContentType + - planConfig + properties: + id: + type: string + description: Unique id of the plan 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: 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 + currentConfigAddress: + type: string + format: uri-reference + description: A reference address to the current configuration associated with the configuration in this descriptor + example: "http://example.org/3gpp/ProvMnS/v1" + applyMode: + type: string + enum: [ATOMIC, BEST_EFFORT, STOP_ON_ERROR] ##EDITOR - SKIP_ON_ERROR open in stage 2 + default : "BEST_EFFORT" + description: Specifies the execution behavior when the plan is activated + example: "BEST_EFFORT" + lastModifiedAt: + type: string + format: date-time + description: the last time the plan was modified + example: "2025-03-06T16:50:26-08:00" + validationState: + type: string + enum: [NOT_VALIDATED, VALIDATING, VALID, INVALID] + default : "NOT_VALIDATED" + description: The validation state of the plan. + example: "NOT_VALIDATED" + lastValidatedAt: + type: string + format: date-time + description: last time the plan was validated + example: "2025-03-06T16:50:29-08:00" + planConfigContentType: + type: string + enum: + - application/vnd.3gpp.json-patch+json + - application/vnd.3gpp.yang-patch+json + description: The format/type of the configuration in planConfig + example: "application/vnd.3gpp.yang-patch+json" + planConfig: + description: "The plan configuration changes" + ##EDITOR's format is TBD + PlanConfigurationDescriptorResponse: + type: object + required: + - id + - applyMode + - lastModifiedAt + - validationState + - planConfigContentType + - planConfig + allOf: + - $ref: '#/components/schemas/PlanConfigurationDescriptor' + properties: + _links: + type: object + description: Hypermedia links for plan descriptor + allOf: + - $ref: '#/components/schemas/SelfLink' + example: + self: + href: "{root-url}/ProvMnS/v1/plan-descriptors/pd-001" + templated: true + type: "application/json" + title: "The newly created PlanConfigurationDescriptor" + + 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" + 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" + applyMode: + type: string + enum: [ATOMIC, BEST_EFFORT, STOP_ON_ERROR] ##EDITOR - "SKIP_ON_ERROR" under discussion in stage 2 + default : "BEST_EFFORT" + description: Specifies the execution behavior when the plan configuration group is activated + example: "BEST_EFFORT" + lastModifiedAt: + type: string + format: date-time + description: the last time the plan was modified + example: "2025-03-06T16:50:26-08:00" + validationState: + type: string + enum: [NOT_VALIDATED, VALIDATING, VALID, INVALID] + default : "NOT_VALIDATED" + description: The validation state for the last time plan configuration group was validated + example: "NOT_VALIDATED" + 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: + type: object + required: + - identifier + properties: + type: + type: string + enum: [PLAN, PLAN_GROUP] + default: PLAN + identifier: + type: string + example: [{"type" : "PLAN", "identifier" : "plan-descriptor-001"}, {"type" : "PLAN_GROUP", "identifier" : "plan-group-descriptor-001"}] + + PlanConfigurationGroupDescriptorResponse: + type: object + required: + - id + - applyMode + - validationState + - isOrdered + - isFailOnMemberConflicts + - members + allOf: + - $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' + properties: + _links: + type: object + description: Hypermedia links for plan descriptor + allOf: + - $ref: '#/components/schemas/SelfLink' + example: + self: + href: "{root-url}/ProvMnS/v1/plan-group-descriptors/pgd-001" + templated: true + type: "application/json" + title: "The newly created PlanConfigurationGroupDescriptor" + + TriggerDescriptor: + type: object + required: + - conditionExpression + - evaluationPeriod + properties: + id: + type: string + description: Unique id of the plan configuration descriptor + example: "trigger-001" + name: + type: string + description: Descriptive name of the trigger descriptor + example: "Rollout-5G-Dublin-East" + description: + type: string + description: Used to describe the purpose of the trigger + example: "This is the plan for the new 5G rollout in Dublin east." + version: + type: string + description: an optional version for the Trigger Descriptor + example: "v1.0" + customProperties: + type: object + description: A dynamic set of custom properties provided by client + additionalProperties: true + example: + technology-type: NR + location: Dublin + conditionExpression: + type: string + description: The condition expression ##BALAZS JEX on NRM - OPEN + activationJobs: + type: array + items: + type : string + description: The identifiers of one or more activation jobs that shall be triggered by this condition. + startAt: + type: string + format: date-time + description: The date and time at which the evaluation of the condition expression shall start. The evaluation result is set to "False" before that date and time. If the information element is not specified, evaluation of the trigger condition shall start immediately. + example: "2025-03-06T16:50:26-08:00" + stopAt: + type: string + format: date-time + description: The date and time at which the evaluation of the condition expression shall stop. The evaluation result is set to "False" after that date and time. If the information element is not specified, evaluation of the trigger condition shall continue until the deletion of the trigger condition descriptor. + example: "2025-03-06T16:50:26-08:00" + currentEvaluationResult: + type: boolean + default : false + description: The current result of evaluating the "condition-expression". + example: false + lastModifiedAt: + type: string + format: date-time + description: The date and time at which the trigger condition was modified the last time by a MnS consumer. Upon creation of the trigger condition descriptor the value of the information element is set to the date and time at which the descriptor is created. + example: "2025-03-06T16:50:29-08:00" + lastTriggeredAt: + type: string + format: date-time + description: Th date and time at which the evaluation result of the trigger condition changed the last time from "False" to "True". + example: "2025-03-06T16:50:29-08:00" + isTriggerActive: + type: boolean + default : false + description: The indication if the trigger can start activation jobs (trigger is active), or if the trigger cannot start activation jobs (trigger is inactive). + example: false + isTriggerOnce: + type: boolean + default : true + description: The boolean indication, if the trigger is disarmed after the first firing. + example: false + evaluationPeriod: + type: integer + description: The evaluation period specifies the interval of time in seconds between two consecutive condition expression evaluations. + hysteresis: + type: integer + description: The hysteresis, when present, specifies that the trigger shall not be activated immediately when the evaluation result changes from false to true or a specified number of times. Values greater or equal to 1 are allowed + + TriggerDescriptorResponse: + type: object + required: + - id + - conditionExpression + - evaluationPeriod + - isTriggerOnce + - currentEvaluationResult + - isTriggerActive + allOf: + - $ref: '#/components/schemas/TriggerDescriptor' + properties: + _links: + type: object + description: Hypermedia links for trigger descriptor + allOf: + - $ref: '#/components/schemas/SelfLink' + example: + self: + href: "{root-url}/ProvMnS/v1/trigger-descriptors/trigger-001" + templated: true + type: "application/json" + title: "The newly created TriggerDescriptor" + + DescriptorListEntry: + type: array + items: + type: object + properties: + id: + type: string + description: id of the descriptor. + example: plan-descriptor-1 + name: + type: string + description: name of the descriptor. + example: Dublin East Rollout + description: + type: string + description: description/purpose of the descriptor. + example: plan-descriptor-1 + required : + - id + - name + + JobListEntry: + type: object + allOf: + - $ref: '#/components/schemas/JobState' + 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 + required : + - id + - name + - jobState + + PlanActivationJob: + type: object + allOf: + - $ref: '#/components/schemas/JobState' + properties: + id: + type: string + description: id of the activation job + example: "job-id-3985199134" + name: + type: string + description: Name of the activation job + example: "Dublin East Cell Deployment" + description: + type: string + description: Human-readable description of the job + example: "Optimize the Dublin area network" + createdFallbackConfigDescrId: ##EDITOR is the name OK ? + type: string + description: Id of the created Fallback Plan Configuration Descriptor + example: "fallback-plan-descriptor-001" + isFallbackEnabled: + type: boolean + description: Whether fallback should be enabled for this job + default: true + serviceImpact: + type: string + enum: [LEAST_SERVICE_IMPACT, SHORTEST_TIME] + description: Additional job-specific parameters + default: "SHORTEST_TIME" + isImmediateActivation: + type: boolean + description: specifies if the activation job shall start immediately or, alternatively, by conditional activation. + default: true + jobDetails: + allOf: + - $ref: '#/components/schemas/JobDetails' + jobState: + allOf: + - $ref: '#/components/schemas/JobState' + activationState: + allOf: + - $ref: '#/components/schemas/ActivationState' + activationDetails: + allOf: + - $ref: '#/components/schemas/LinkObject' + - type: object + properties: + href: + type: string + title: A URI reference to the activation details + example: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/activation-details" ##EDITOR: Why do we force the user to ask for the details in a separate request? + title: ##EDITOR at least the summary should be prsent here. + type: string + enum: + - "Link to the activation details" + method: + type: string + enum: + - "GET" + type: + type: string + description: The content type expected when following this link (MIME type). + default: "application/json" + sourceIdentity: + type: array + description: The user 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 + oneOf: + - type: object + required: + - planConfigDescrId # Alt.1 planConfigDescrId + properties: + planConfigDescrId: + type: string + description: Unique id reference to the plan descriptor to activate + example: "planxyz" + - type: object + required: + - planConfigDescr # Alt.2 planConfigDescr embedded + properties: + planConfigDescr: + type: object + description: Inline plan configuration descriptor to activate + allOf: + - $ref: '#/components/schemas/PlanConfigurationDescriptor' + example: + name: "myjob-111" + applyMode: "BEST_EFFORT" + customProperties: { + techology-type: "NR", + indoor: false + } + planConfig: + ... + - type: object + required: + - planConfigGroupDescrId # Alt.3 planConfigGroupDescrId + properties: + planConfigGroupDescrId: + type: string + description: Unique id reference to the plan group descriptor to activate + example: "plan-group-xyz" + - type: object + required: + - planConfigGroupDescr # Alt.4 planConfigGroupDescr embedded + properties: + planConfigGroupDescr: + type: string + description: Inline plan group descriptor to activate + allOf: + - $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' + ##BALAZS Alt5. fallbackdescriptorId missing + example: + { + id : "myjob-111", + name : "5G-Dublin-East-Rollout", + description : "Optimize the 5G network in Dublin East", + isFallbackEnabled : true, + serviceImpact : "SHORTEST_TIME", + isImmediateActivation : true, + jobState : "CREATED", + jobDetails : "", + startedAt : "", + activationState : "NOT_STARTED", + activationDetails : { + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/activation-details", + templated: true, + type: "application/json", + title: "The activation details of the plan configuration(s)", + method : "GET" + }, + planConfigDescrId : "plan-descriptor-001", + } + additionalProperties : true + + PlanActivationJobRequest: + type: object + allOf: + - $ref: '#/components/schemas/PlanActivationJob' + example: + { + "name" : "5G-Dublin-East-Rollout", + "description" : "Optimize the 5G network in Dublin East", + "planConfigDescr" : { + "applyMode" : "ATOMIC", + "customProperties" : { + "technology-type": "NR", + "location": "Dublin" + }, + "planConfigContentType" : "application/vnd.3gpp.yang-patch+json", + "planConfig": { + ... + } + } + } + + PlanActivationJobResponse: + type: object + required: + - id + - jobState + - jobDetails + - activationState + - activationDetails + - isImmediateActivation + - isFallbackEnabled + - serviceImpact + allOf: + - $ref: '#/components/schemas/PlanActivationJob' + properties: + _links: + description: Hypermedia links for this resource, including fixed and dynamic relations + allOf: + - $ref: '#/components/schemas/JobLinks' + - type: object + properties: + self: + allOf: + - $ref: '#/components/schemas/LinkObject' ##EDITOR Any other link will conform to LinkObject schema but we shall specify which links to expect + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/{planActivationJobId}" + title: + type: string + enum: + - "Link to the plan activation job" + method: + type: string + enum: + - "GET" + example: + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/activation-job-001" + title: "Link to the plan activation job" + type: "application/json" + templated: true + method: GET + fallback: + allOf: + - $ref: '#/components/schemas/LinkObject' + description: A URI reference to the fallback plan descriptor + example: + href: "{apiRoot}/ProvMnS/v1/plan-descriptor/myjob-111-fallback" + templated: true + type: "application/json" + title: "A URI reference to the fallback plan descriptor" + method: GET + ##EDITOR other links are missing. We have more in the examples -> additionalProperties to allow any other dynamic links + additionalProperties: + $ref: '#/components/schemas/LinkObject' + example: + self: + href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111" + templated: true + type: "application/json" + title: "The newly created activation job" + method : "GET" + planDescriptor: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/planxyz" + templated: true + type: "application/json" + title: "plan descriptor link" + method : "GET" + status: + href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111/status" + templated: true + type: "application/json" + title: "activation status link" + method : "GET" + cancel: + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/status/jos-state" + templated: true + type: "application/json" + title: "cancel the job" + method : "PUT" + fallbackPlan: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/myfallback-plan-111" + templated: true + type: "application/json" + title: "fallback plan descriptor link" + method : "GET" + + CancelRequest: + type: object + required: + - jobState + properties: + jobState: + type: string + enum : + - CANCELLING + description: set to CANCELLING to cancel a job + example: CANCELLING + + PlanValidationJob: + type: object + allOf: + - $ref: '#/components/schemas/JobState' + properties: + id: + type: string + description: id of the validation job + example: "job-id-3985199134" + 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" + jobDetails: + allOf: + - $ref: '#/components/schemas/JobDetails' + jobState: + allOf: + - $ref: '#/components/schemas/JobState' + validationState: + allOf: + - $ref: '#/components/schemas/ValidationState' + validationDetails: + allOf: + - $ref: '#/components/schemas/LinkObject' + - type: object + properties: + href: + type: string + title: A URI reference to the validation details + example: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/validation-details" + title: + type: string + enum: + - "Link to the validation details" + method: + type: string + enum: + - "GET" + type: + type: string + description: The content type expected when following this link (MIME type). + default: "application/json" + sourceIdentity: + type: array + description: The user 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 + oneOf: + - type: object + required: + - planConfigDescrId # Alt.1 planConfigDescrId + properties: + planConfigDescrId: + type: string + description: Unique id reference to the plan descriptor to activate + example: "planxyz" + - type: object + required: + - planConfigDescr # Alt.2 planConfigDescr embedded + properties: + planConfigDescr: + type: object + description: Inline plan configuration descriptor to activate + allOf: + - $ref: '#/components/schemas/PlanConfigurationDescriptor' + example: + name: "myjob-111" + applyMode: "BEST_EFFORT" + customProperties: { + techology-type: "NR", + indoor: false + } + planConfig: + ... + - type: object + required: + - planConfigGroupDescrId # Alt.3 planConfigGroupDescrId + properties: + planConfigGroupDescrId: + type: string + description: Unique id reference to the plan group descriptor to activate + example: "plan-group-xyz" + - type: object + required: + - planConfigGroupDescr # Alt.4 planConfigGroupDescr embedded + properties: + planConfigGroupDescr: + type: string + description: Inline plan group descriptor to activate + allOf: + - $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' + ##EDITOR ALt.5 fallback missing + example: + { + id : "myjob-111", + name : "5G-Dublin-East-Rollout", + description : "Optimize the 5G network in Dublin East", + isFallbackEnabled : true, + serviceImpact : "SHORTEST_TIME", + isImmediateActivation : true, + jobState : "CREATED", + jobDetails : "", + startedAt : "", + activationState : "NOT_STARTED", + activationDetails : { + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/activation-details", + templated: true, + type: "application/json", + title: "The activation details of the plan configuration(s)", + method : "GET" + }, + planConfigDescrId : "plan-descriptor-001", + } + additionalProperties : true + + PlanValidationJobRequest: + type: object + allOf: + - $ref: '#/components/schemas/PlanValidationJob' + example: + { + "name" : "5G-Dublin-East-Rollout", + "description" : "Optimize the 5G network in Dublin East", + "planDescriptor" : { + "applyMode" : "ATOMIC", + "customProperties" : { + "technology-type": "NR", + "location": "Dublin" + }, + "planConfig": { + ... + } + } + } + + PlanValidationJobResponse: + type: object + required: + - id + - jobState + - jobDetails + - validationState + - validationDetails + allOf: + - $ref: '#/components/schemas/PlanValidationJob' + properties: + _links: + description: Hypermedia links for this resource, including fixed and dynamic relations + allOf: + - $ref: '#/components/schemas/JobLinks' + - type: object + properties: + self: + allOf: + - $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/plan-validation-jobs/{planValidationJobId}" + title: + type: string + enum: + - "Link to the plan validation job" + method: + type: string + enum: + - "GET" # This means the method MUST be "GET" + example: + href: "{apiRoot}/ProvMnS/v1/plan-validation-jobs/validation-job-001" + title: "Link to the plan validation job" + type: "application/json" + templated: true + method: GET + # additionalProperties to allow any other dynamic links + additionalProperties: + $ref: '#/components/schemas/LinkObject' + example: + self: + href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111" + templated: true + type: "application/json" + title: "The newly created activation job" + method : "GET" + planDescriptor: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/planxyz" + templated: true + type: "application/json" + title: "plan descriptor link" + method : "GET" + status: + href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111/status" + templated: true + type: "application/json" + title: "activation status link" + method : "GET" + cancel: + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/cancel" + templated: true + type: "application/json" + title: "cancel the job" + method : "POST" + fallbackPlan: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/myfallback-plan-111" + templated: true + type: "application/json" + title: "fallback plan descriptor link" + method : "GET" + + AbstractChangeDefinition: + type: object + properties: + operation: + type: string + enum: [create, merge, update, remove] + 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" + value: + type: object + additionalProperties: true # Allows any nested properties within 'value' + description: Value to apply (for create/merge/remove operations) + + Change: + allOf: + - $ref: '#/components/schemas/AbstractChangeDefinition' + - type: object + properties: + changeId: + type: string + description: Unique identifier for this change + example: "opId-001" + additionalProperties: true # Allows any nested properties within 'value' + required: + - operation + - target + + JobLinks: + type: object + allOf: + - $ref: '#/components/schemas/SelfLink' + properties: + planDescriptor: + description: A URI reference to the plan (or plan group) configuration descriptor + allOf: + - $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/plan-descriptors/{planDescriptorId}" + title: + type: string + enum: + - "Link to the plan (or plan group) configuration descriptor" + method: + type: string + enum: + - "GET" # This means the method MUST be "GET" + example: + href: "{apiRoot}/ProvMnS/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' # Any other link will conform to LinkObject schema + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/{jobId}/status" + title: + type: string + enum: + - "Link to GET the job status" + method: + type: string + enum: + - "GET" # This means the method MUST be "GET" + description: A URI reference to the status information + example: + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/status" + title: "Link to GET the job status" + type: "application/json" + templated: true + method: GET + cancel: + allOf: + - $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/plan-{job-type}-jobs/{jobId}/status/job-state" + title: + type: string + enum: + - "Link to cancel the job" + method: + type: string + enum: + - "PUT" # This means the method MUST be "PUT" + description: A URI reference to cancel the job + example: + href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/cancel" + title: "Link to cancel the job" + type: "application/json" + templated: true + method: POST + + JobState: + type: string + enum: [CREATED, RUNNING, COMPLETED, FAILED, CANCELLING, CANCELLED] + example: "COMPLETED" + + JobDetails: + properties: + jobInformation: + type: string + additionalProperties: true + + ActivationJobStatus: + properties: + jobState: + allOf: + - $ref: '#/components/schemas/JobState' + example: "COMPLETED" + activationState: + allOf: + - $ref: '#/components/schemas/ActivationState' + example: "ACTIVATED" + 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" + + ValidationJobStatus: + properties: + jobState: + allOf: + - $ref: '#/components/schemas/JobState' + example: "COMPLETED" + validationState: + allOf: + - $ref: '#/components/schemas/ValidationState' + example: "VALID" + 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" + + 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: + results: + type: array + items: + type: object + properties: + planDescriptorId: + type: string + example: "planconfig-descriptor-001" + changes: ##EDITOR format is TBD + type: array + items: + $ref: '#/components/schemas/ChangeStatus' + summary: + $ref: '#/components/schemas/SummaryStatus' + example: + { + "results": { ...}, ##EDITOR format is TBD + "summary" : { + "unprocessed": 0, + "succeeded": 2, + "failed": 3 + } + } + + ValidationState: + type: string + enum: [NOT_VALIDATED, VALIDATING, VALIDATED, VALIDATION_FAILED, PARTIALLY_VALIDATED] + example: "VALIDATED" + + ActivationState: + type: string + enum: [NOT_STARTED, VALIDATING, ACTIVATED, ACTIVATION_FAILED, PARTIALLY_ACTIVATED, ACTIVATION_FAILED_ROLLED_BACK, ACTIVATION_FAILED_ROLLBACK_FAILED] + example: "ACTIVATED" + + ChangeStatus: + type: object + properties: + changeId: + type: string + example: "changeId-001" + state: + type: string + enum: [SUCCEEDED, FAILED, UNPROCESSED] + default: UNPROCESSED + example: "SUCCEEDED" + target: + type: string + example: "/SubNetwork=1/MeContext=2/ManagedElement=3" + errors: + type: array + items: + $ref: '#/components/schemas/ErrorDetail' + conflicts: + type: array + items: + $ref: '#/components/schemas/Conflict' + required: + - changeId ##EDITOR yes or no + - target + - state + example: + changeId: changeId-002-update-config + target: /SubNetwork=1/MeContext=2/ManagedElement=3 + state: FAILED + errors: + - type: VALIDATION_ERROR + title: Validation Error + status: 400 + reason: NEW_ATTRIBUTE_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 + + SummaryStatus: + type: object + properties: + unprocessed: + type: integer + example: 1 + succeeded: + type: integer + example: 3 + failed: + type: integer + example: 3 + rollbackSucceeded: + type: integer + example: 0 + rollbackFailed: + type: integer + example: 0 + + Conflict: + type: object + allOf: + - $ref: '#/components/schemas/Change' + properties: + planDescriptorId: ##EDITOR if missing the conlict is in same plan config descriptor as the 'source' change -> comment to be added in description + type: string + change: + $ref: '#/components/schemas/Change' + conflictingChanges: + type: array + items: + $ref: '#/components/schemas/ConflictingChange' + example: + { + "planDescriptorId" : "plan-descriptor-001", + "changeId": "optimization-change-A", + "operation": "merge", + "target": "/_3gpp-common-subnetwork:SubNetwork=HQ/NRCellDU=cell-22", + "value" : { + "attributes" : { + "some-attribute-name-a" : "some-attribute-value-b" + } + }, + "conflictingChanges": [ + { + "planDescriptorId": "plan-emergency-fix", + "change": { + "changeId": "fix-power-issue-X", + "operation": "merge", + "target": "/_3gpp-common-subnetwork:SubNetwork=HQ/NRCellDU=cell-22", + "value" : { + "attributes" : { + "some-attribute-name-x" : "some-attribute-value-y" + } + }, + }, + "conflictType": "VALUE_OVERWRITE", + "conflictMessage": "This change attempts to set 'transmitPower' to 45, but 'fix-power-issue-X' from 'plan-emergency-fix' sets it to 40. Only one value can persist.", + "severity": "HIGH" + } + ] + } + + ConflictingChange: + type: object + properties: + planDescriptorId: ##EDITOR if missing the conlict is in same plan config descriptor as the 'source' change -> to add to description + type: string + change: + $ref: '#/components/schemas/Change' + conflictType: + type: string + conflictMessage: + type: string + severity: + type: string + enum: + - LOW + - MEDIUM + - HIGH + - UNKNOWN + default: UNKNOWN + required: + - change + - conflictType + - severity + + ErrorDetail: + type: object + properties: + title: + type: string + description: A short, human-readable summary of the problem type + example: "Data already exists; cannot be created" + status: + type: integer + format: int32 + enum: + - 400 + - 403 + - 404 + - 405 + - 406 + - 408 + - 410 + - 411 + - 413 + - 414 + - 415 + - 422 + - 426 + - 429 + - 451 + type: + type: string + description: The type of the error + enum: + - VALIDATION_ERROR + - REQUEST_OBJECT_TREE_MISMATCH + - IE_NOT_FOUND + - MODIFICATION_NOT_ALLOWED + - RETRIEVAL_NOT_ALLOWED + - SERVER_LIMITATION + - SERVICE_DISABLED + - APPLICATION_LAYER_ERROR + reason: + type: string + enum: + - RESPONSE_TOO_LARGE + - NO_DATA_ACCESS + - QUERY_MALFORMED + - QUERY_PARAM_NAMES_INVALID + - QUERY_PARAM_VALUES_INVALID + - QUERY_PARAMS_MISSING + - QUERY_PARAMS_INCONSISTENT + - ATTRIBUTES_NOT_READABLE + - QUERY_PARAMS_TOO_COMPLEX + - NEW_ATTRIBUTE_VALUE_INVALID + - NEW_ATTRIBUTE_NAME_INVALID + - ATTRIBUTE_NOT_WRITABLE + - ATTRIBUTE_INVARIANT + - ATTRIBUTE_NOT_FOUND + - OBJECT_CREATION_NOT_ALLOWED + - OBJECT_DELETION_NOT_ALLOWED + - NEW_OBJECT_CLASS_NAME_INVALID + - NEW_OBJECT_REPRESENTATION_INVALID + - NEW_OBJECT_CONTAINMENT_INVALID + - NEW_OBJECTS_ID_EXISTS + - NEW_OBJECTS_PARENT_NOT_FOUND + - NEW_OBJECT_ATTRIBUTE_VALUE_MISSING + - OBJECTS_CARDINALITY_INVALID + - OBJECT_NOT_A_LEAF + - OBJECT_NOT_FOUND + - OP_UNKNOWN + - RESOURCE_LOCKED + - SERVICE_LOCKED + - UNKNOWN + example: "UNKNOWN" + detail: + type: string + description: A human-readable explanation specific to this occurrence of the problem. + example: "NRCellDU=1234 already exists in the network" + path: + 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 + - title + - status + + # Use oneOf and discriminator to define the mapping + oneOf: + # Define a specific schema for each 'type' enum value + - $ref: '#/components/schemas/ValidationErrorDetails' + - $ref: '#/components/schemas/RequestObjectTreeMismatchDetails' + - $ref: '#/components/schemas/IENotFoundDetails' + - $ref: '#/components/schemas/ModificationNotAllowedDetails' + - $ref: '#/components/schemas/RetrievalNotAllowedDetails' + - $ref: '#/components/schemas/ServerLimitationDetails' + - $ref: '#/components/schemas/ServiceDisabledDetails' + - $ref: '#/components/schemas/ApplicationLayerErrorDetails' + # Add other specific error types here + + discriminator: + propertyName: type # This is the property that determines which oneOf schema applies + mapping: + VALIDATION_ERROR: '#/components/schemas/ValidationErrorDetails' + REQUEST_OBJECT_TREE_MISMATCH: '#/components/schemas/RequestObjectTreeMismatchDetails' + IE_NOT_FOUND: '#/components/schemas/IENotFoundDetails' + MODIFICATION_NOT_ALLOWED: '#/components/schemas/ModificationNotAllowedDetails' + RETRIEVAL_NOT_ALLOWED: '#/components/schemas/RetrievalNotAllowedDetails' + SERVER_LIMITATION: '#/components/schemas/ServerLimitationDetails' + SERVICE_DISABLED: '#/components/schemas/ServiceDisabledDetails' + APPLICATION_LAYER_ERROR: '#/components/schemas/ApplicationLayerErrorDetails' + + # Individual schemas for each specific error type + ValidationErrorDetails: + type: object + properties: + type: + type: string + enum: [VALIDATION_ERROR] + title: + type: string + enum: ["Validation Error"] + status: + type: integer + enum: [400] + + RequestObjectTreeMismatchDetails: + type: object + properties: + type: + type: string + enum: [REQUEST_OBJECT_TREE_MISMATCH] + title: + type: string + enum: ["Request Object Tree Mismatch"] + status: + type: integer + enum: [422] + + IENotFoundDetails: + type: object + properties: + type: + type: string + enum: [IE_NOT_FOUND] + title: + type: string + enum: ["Information Element Not Found"] + status: + type: integer + enum: [400] + + ModificationNotAllowedDetails: + type: object + properties: + type: + type: string + enum: [MODIFICATION_NOT_ALLOWED] + title: + type: string + enum: ["Modification Not Allowed"] + status: + type: integer + enum: [403] + + RetrievalNotAllowedDetails: + type: object + properties: + type: + type: string + enum: [RETRIEVAL_NOT_ALLOWED] + title: + type: string + enum: ["Retrieval Not Allowed"] + status: + type: integer + enum: [403] + + ServerLimitationDetails: + type: object + properties: + type: + type: string + enum: [SERVER_LIMITATION] + title: + type: string + enum: ["Server Limitation"] + status: + type: integer + enum: [500] + + ServiceDisabledDetails: + type: object + properties: + type: + type: string + enum: [SERVICE_DISABLED] + title: + type: string + enum: ["Service Disabled"] + status: + type: integer + enum: [503] + + ApplicationLayerErrorDetails: + type: object + properties: + type: + type: string + enum: [APPLICATION_LAYER_ERROR] + title: + type: string + enum: ["Application Layer Error"] + status: + type: integer + enum: [500] + + LinkObject: + type: object + description: Defines the structure of a single hypermedia link. + properties: + href: + type: string + format: uri-reference # Use uri-reference for relative paths (allows for absolute or relative uri) + 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 + + SelfLink: + type: object + description: Hypermedia links for this resource, including fixed and dynamic relations. + properties: + self: + allOf: + - $ref: '#/components/schemas/LinkObject' + description: A link to the resource itself. + # additionalProperties to allow any other dynamic links + additionalProperties: + $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema + required: + - self + example: # demonstrates a typical _links object in an actual response + self: + href: "{root-url}/ProvMnS/v1/plan-descriptors/pd-001" + templated: true + type: "application/json" + title: "The newly created PlanConfigurationDescriptor" + help: + href: "{root-url}/help-service/v1/topics/plan-descriptors" + templated: true + type: "application/json" + title: "online help for the plan descriptor" + + examples: + # Reusable Configuration Change Examples + AddNrCellChange: + summary: Add a new NR Cell (create operation) + value: + operation: create + changeId: add-nr-cell-001 + description: Add new NR cell for initial deployment in Dublin-1 area. + target: /_3gpp-common-subnetwork:SubNetwork=Irl/_3gpp-common-mecontext:MeContext=Dublin-1/_3gpp_nrm_managedelement:ManagedElement=1/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1/_3gpp_nrm_nrcelldu:NRCellDU=4 + value: + ... + UpdateNrCellChange: + summary: Update an existing NR Cell (merge operation) + value: + operation: merge + changeId: update-nr-cell-002 + description: Update administrativeState for existing NRCellDU=1. + target: /_3gpp-common-subnetwork:SubNetwork=North/_3gpp-common-mecontext:MeContext=Dublin-1/_3gpp_nrm_managedelement:ManagedElement=ENB-A/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1/_3gpp_nrm_nrcelldu:NRCellDU=1 + value: + ... + RemoveNrCellChange: + summary: Remove an NR Cell (remove operation) + value: + operation: remove + changeId: remove-nr-cell-003 + description: Decommission NRCellDU=3. + target: /_3gpp-common-subnetwork:SubNetwork=Irl/_3gpp-common-mecontext:MeContext=Dublin-1/_3gpp_nrm_managedelement:ManagedElement=1/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1/_3gpp_nrm_nrcelldu:NRCellDU=3 \ No newline at end of file -- GitLab From d7f4a316ee1f9ec7c7f6187e3a67292c03490f99 Mon Sep 17 00:00:00 2001 From: lengyelb Date: Fri, 15 Aug 2025 17:01:05 +0200 Subject: [PATCH 2/4] Edit TS28572_PlanManagement.yaml --- OpenAPI/TS28572_PlanManagement.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OpenAPI/TS28572_PlanManagement.yaml b/OpenAPI/TS28572_PlanManagement.yaml index a9b049958..174587a62 100644 --- a/OpenAPI/TS28572_PlanManagement.yaml +++ b/OpenAPI/TS28572_PlanManagement.yaml @@ -1260,7 +1260,7 @@ components: location: Dublin conditionExpression: type: string - description: The condition expression ##BALAZS JEX on NRM - OPEN + description: The condition expression ##EDITOR JEX on NRM - OPEN activationJobs: type: array items: @@ -1488,7 +1488,7 @@ components: description: Inline plan group descriptor to activate allOf: - $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' - ##BALAZS Alt5. fallbackdescriptorId missing + ##EDITOR Alt5. fallbackdescriptorId missing example: { id : "myjob-111", -- GitLab From ef9e0f8cd3b0f68dfcf283d6efaeeca19d0a9ae7 Mon Sep 17 00:00:00 2001 From: lengyelb Date: Tue, 26 Aug 2025 15:22:43 +0200 Subject: [PATCH 3/4] Edit TS28572_PlanManagement.yaml --- OpenAPI/TS28572_PlanManagement.yaml | 1192 +++++++++++++++------------ 1 file changed, 662 insertions(+), 530 deletions(-) diff --git a/OpenAPI/TS28572_PlanManagement.yaml b/OpenAPI/TS28572_PlanManagement.yaml index 174587a62..b1ec7c8cf 100644 --- a/OpenAPI/TS28572_PlanManagement.yaml +++ b/OpenAPI/TS28572_PlanManagement.yaml @@ -1,8 +1,20 @@ -openapi: 3.0.0 ##EDITOR get, delete Fallback; FallbackConfigurationDescriptor missing +openapi: 3.0.0 info: title: 3GPP Plan Provisioning Management API - version: 1.0.0 + version: 19.0.0 description: API for managing network configuration plans and related jobs +externalDocs: + description: 3GPP TS 28.572; Generic management services + url: http://www.3gpp.org/ftp/Specs/archive/28_series/28.572/ +servers: + - url: '{MnSRoot}/ProvPlanMnS/{MnSVersion}' + variables: + MnSRoot: + description: See clause 4.4.2 of TS 32.158 + default: http://example.com/PlanManagement + MnSVersion: + description: Version number of the OpenAPI definition + default: v1 paths: /plan-descriptors: @@ -28,7 +40,7 @@ paths: "location": "Dublin" }, "currentConfigAddress": "http://example.org/3gpp/ProvMnS/v1", - "planConfigContentType" : "application/vnd.3gpp.yang-patch+json", + "configurationContentType" : "application/vnd.3gpp.yang-patch+json", "planConfig": { ... } @@ -149,12 +161,6 @@ paths: } } responses: - '200': - description: Plan descriptor replaced successfully - content: - application/json: - schema: - $ref: '#/components/schemas/PlanConfigurationDescriptorResponse' ##EDITOR why is a return data needed? Is it not trivial ? TODO remove 200 '204': description: Plan descriptor replaced successfully. No content is returned '400': @@ -190,7 +196,7 @@ paths: content: application/problem+json: schema: - $ref: '#/components/schemas/ErrorDetail' ##EDITOR The example in swagger is very strange. The example cannot nbe the same for put and delete. TODO + $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: @@ -319,7 +325,7 @@ paths: "name": "Rollout-5G-Dublin-East", "version" : "1.0.0", "description": "This is the plan for the new 5G rollout in Dublin east.", - "applyMode" : "BEST_EFFORT", + "activationMode" : "BEST_EFFORT", "isOrdered" : true, "isFailOnMemberConflicts" : true, "members": [{"type" : "PLAN", "identifier" : "plan-descriptor-001"}, {"type" : "PLAN_GROUP", "identifier" : "plan-group-descriptor-001"}] @@ -331,7 +337,7 @@ paths: application/json: schema: $ref: '#/components/schemas/PlanConfigurationGroupDescriptorResponse' - '400': ##EDITOR should we use 422 ? + '400': description: Invalid request parameters or malformed input. content: application/problem+json: @@ -365,7 +371,7 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/ErrorDetail' - '409': ##EDITOR can you delete a plan or group that is being activated IMHO not. Add here. Can a plan/group be deleted if it is part of a validationJob? IMHJO yes + '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: @@ -378,6 +384,90 @@ paths: 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-descriptor/{id}: + parameters: + - in: path + name: id + schema: + type: string + description: Unique identifier of the fallback descriptor. + example: "Fallback-Dublin-South-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: @@ -483,12 +573,6 @@ paths: schema: $ref: '#/components/schemas/TriggerDescriptor' responses: - '200': ##EDITOR why do we need 200? Isnt 204 enough ? - description: Trigger descriptor replaced successfully - content: - application/json: - schema: - $ref: '#/components/schemas/TriggerDescriptorResponse' '204': description: Trigger descriptor created successfully '400': @@ -532,19 +616,19 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-activation-jobs: ##EDITOR remove plan- from activation-job ActivationJob generally + /activation-jobs: post: tags: - Activation Management - summary: Create a new plan activation job ##EDITOR or group or fallbackdescr - description: Creates and starts a new plan activation 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: createPlanActivationJob + 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/PlanActivationJobRequest' + $ref: '#/components/schemas/ActivationJobRequest' responses: '201': description: Plan activation job created successfully. @@ -555,11 +639,11 @@ paths: schema: type: string format: uri-reference - example: "/plan-activation-jobs/myjob-111" + example: "/activation-jobs/myjob-111" content: application/json: schema: - $ref: '#/components/schemas/PlanActivationJobResponse' + $ref: '#/components/schemas/ActivationJob' '400': description: Invalid request payload or parameters (e.g., malformed JSON, missing required fields). content: @@ -577,8 +661,8 @@ paths: tags: - Activation Management summary: Get plan activation jobs - description: Retrieve a list of plan activation jobs. ##EDITOR describe that the order of items is vendor specific, but it shall be fixed. - operationId: getPlanActivationJobs + description: Retrieve a list of plan activation jobs. + operationId: getActivationJobs parameters: - in: query name: job-state @@ -586,21 +670,6 @@ paths: $ref: '#/components/schemas/JobState' description: Filter jobs by their current state. example: "RUNNING" - - in: query - name: limit - schema: - type: integer ##EDIOR this paging is slightly broken. Prposal to remove. - format: int32 - minimum: 1 - description: Maximum number of jobs to return. - - in: query - name: offset - schema: - type: integer - format: int32 - minimum: 0 - default: 0 - description: Number of jobs to skip before starting to collect the result set. responses: '200': description: List of plan activation jobs retrieved successfully. @@ -623,7 +692,7 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-activation-jobs/{id}: + /activation-jobs/{id}: parameters: - $ref: '#/components/parameters/jobId' get: @@ -631,14 +700,14 @@ paths: - 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: getPlanActivationJobById + operationId: getActivationJobById responses: '200': description: Job details retrieved successfully. content: application/json: schema: - $ref: '#/components/schemas/PlanActivationJobResponse' + $ref: '#/components/schemas/ActivationJob' '404': description: Job not found. content: @@ -657,7 +726,7 @@ paths: - 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: deletePlanActivationJobById + operationId: deleteActivationJobById responses: '204': description: Job deleted successfully. No content is returned. @@ -680,15 +749,15 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-activation-jobs/{id}/status: + /activation-jobs/{id}/status: + parameters: + - $ref: '#/components/parameters/jobId' 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: - - $ref: '#/components/parameters/jobId' responses: '200': description: Job status retrieved successfully. @@ -708,38 +777,11 @@ paths: 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: - - $ref: '#/components/parameters/jobId' - 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-activation-jobs/{id}/status/job-state: - parameters: - - $ref: '#/components/parameters/jobId' - put: + patch: tags: - Activation Management - summary: Cancel the activation job by modifying the jobState property ##EDITOR harmonize with stage2 where there is a separate cancelRequest or is-cancel-requested boolean. - description: Cancel the activation job by modifying the jobState property + summary: Cancel the activation job + description: Cancel the activation job operationId: cancelActivationJobById requestBody: required: true @@ -747,21 +789,11 @@ paths: application/json: schema: $ref: '#/components/schemas/CancelRequest' - example: - { - "jobState": "CANCELLING" - } responses: '200': description: Job cancel request was successfully completed '202': description: Job cancel request was accepted and cancellation is ongoing - '400': - description: Bad request . - content: - application/problem+json: - schema: - $ref: '#/components/schemas/ErrorDetail' '404': description: Job not found. content: @@ -769,7 +801,7 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' '422': - description: Semantic error - - perhaps jobState not set to correct value. + description: Semantic error - e.g. job was not in RUNNING state content: application/problem+json: schema: @@ -781,19 +813,42 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-validation-jobs: ##EDITOR remove plan- from the name, see stage2 + /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: + - $ref: '#/components/parameters/jobId' + 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' + + /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: createPlanValidationJob + operationId: createValidationJob requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/PlanValidationJobRequest' + $ref: '#/components/schemas/ValidationJobRequest' responses: '201': description: Plan validation job created successfully. @@ -804,11 +859,11 @@ paths: schema: type: string format: uri-reference - example: "/plan-validation-jobs/myjob-111" + example: "/validation-jobs/myjob-111" content: application/json: schema: - $ref: '#/components/schemas/PlanValidationJobResponse' + $ref: '#/components/schemas/ValidationJob' '400': description: Invalid request payload or parameters (e.g., malformed JSON, missing required fields). content: @@ -827,7 +882,7 @@ paths: - Validation Management summary: Get plan validation jobs description: Retrieve a list of plan validation jobs. - operationId: getPlanValidationJobs + operationId: getValidationJobs parameters: - in: query name: job-state @@ -835,21 +890,6 @@ paths: $ref: '#/components/schemas/JobState' description: Filter jobs by their current status. example: "RUNNING" - - in: query - name: limit - schema: - type: integer ##EDITOR paging is slightly broken. Same as for activtion-jobs - format: int32 - minimum: 1 - description: Maximum number of jobs to return. - - in: query - name: offset - schema: - type: integer - format: int32 - minimum: 0 - default: 0 - description: Number of jobs to skip before starting to collect the result set. responses: '200': description: List of plan validation jobs retrieved successfully. @@ -866,7 +906,7 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-validation-jobs/{id}: + /validation-jobs/{id}: parameters: - $ref: '#/components/parameters/jobId' get: @@ -874,14 +914,14 @@ paths: - 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: getPlanValidationJobById + operationId: getValidationJobById responses: '200': description: Job details retrieved successfully. content: application/json: schema: - $ref: '#/components/schemas/PlanValidationJobResponse' + $ref: '#/components/schemas/ValidationJob' '404': description: Job not found. content: @@ -900,7 +940,7 @@ paths: - 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: deletePlanValidationJobById + operationId: deleteValidationJobById responses: '204': description: Job deleted successfully. No content is returned. @@ -910,12 +950,6 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/ErrorDetail' - '409': - description: Cannot delete job in its current state (e.g., already running). ##EDITOR I think even a running valaidationjob can be deleted. Do we need this? - content: - application/problem+json: - schema: - $ref: '#/components/schemas/ErrorDetail' '500': description: Internal server error. content: @@ -923,7 +957,7 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-validation-jobs/{id}/status: + /validation-jobs/{id}/status: get: tags: - Validation Management @@ -951,8 +985,43 @@ paths: application/problem+json: schema: $ref: '#/components/schemas/ErrorDetail' + patch: + tags: + - Activation Management + summary: Cancel the validation job + description: Cancel the validation job + operationId: cancelActivationJobById + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CancelRequest' + responses: + '200': + description: Job cancel request was successfully completed + '202': + description: Job cancel request was accepted and cancellation is ongoing + '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}/validation-details: + /validation-jobs/{id}/validation-details: get: tags: - Validation Management @@ -961,12 +1030,13 @@ paths: operationId: getValidationDetails parameters: - $ref: '#/components/parameters/jobId' - - name: expand + - name: details in: query - description: Level of detail to return + description: Selects the level of details to return. schema: type: string - enum: [all] + enum: [summary, all] + default: all responses: '200': description: Validation details retrieved successfully @@ -981,38 +1051,28 @@ paths: schema: $ref: '#/components/schemas/ErrorDetail' - /plan-validation-jobs/{id}/status/job-state: + /validation-jobs/{id}/cancel-request: parameters: - $ref: '#/components/parameters/jobId' put: tags: - Validation Management - summary: Cancel the validation job by modifying the jobState property - description: Cancel the validation job by modifying the jobState property ##EDITOR harmonize cancelling with stage2 + summary: Cancel the validation job + description: Cancel the validation job operationId: cancelValidationJobById - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CancelRequest' - example: - { - "jobState": "CANCELLING" - } responses: '200': description: Job cancel request was successfully completed '202': description: Job cancel request was accepted and cancellation is ongoing - '400': - description: Bad request - perhaps jobState not set to correct value. + '404': + description: Job not found. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorDetail' - '404': - description: Job not found. + '422': + description: Semantic error - e.g. job was not in RUNNING state content: application/problem+json: schema: @@ -1048,7 +1108,7 @@ components: PlanConfigurationDescriptor: type: object required: - - planConfigContentType + - configurationContentType - planConfig properties: id: @@ -1079,9 +1139,9 @@ components: format: uri-reference description: A reference address to the current configuration associated with the configuration in this descriptor example: "http://example.org/3gpp/ProvMnS/v1" - applyMode: + activationMode: type: string - enum: [ATOMIC, BEST_EFFORT, STOP_ON_ERROR] ##EDITOR - SKIP_ON_ERROR open in stage 2 + enum: [ATOMIC, BEST_EFFORT, STOP_ON_ERROR] default : "BEST_EFFORT" description: Specifies the execution behavior when the plan is activated example: "BEST_EFFORT" @@ -1101,7 +1161,7 @@ components: format: date-time description: last time the plan was validated example: "2025-03-06T16:50:29-08:00" - planConfigContentType: + configurationContentType: type: string enum: - application/vnd.3gpp.json-patch+json @@ -1110,15 +1170,22 @@ components: example: "application/vnd.3gpp.yang-patch+json" planConfig: description: "The plan configuration changes" - ##EDITOR's format is TBD + oneOf: + - type: array + items: + $ref: '#/components/schemas/Change' + - type: object + additionalProperties: + $ref: '#/components/schemas/Change' + description: A map of changes. The key of the map shall have the same value as the changeId. PlanConfigurationDescriptorResponse: type: object required: - id - - applyMode + - activationMode - lastModifiedAt - validationState - - planConfigContentType + - configurationContentType - planConfig allOf: - $ref: '#/components/schemas/PlanConfigurationDescriptor' @@ -1167,9 +1234,9 @@ components: 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" - applyMode: + activationMode: type: string - enum: [ATOMIC, BEST_EFFORT, STOP_ON_ERROR] ##EDITOR - "SKIP_ON_ERROR" under discussion in stage 2 + 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" @@ -1205,11 +1272,78 @@ components: type: string example: [{"type" : "PLAN", "identifier" : "plan-descriptor-001"}, {"type" : "PLAN_GROUP", "identifier" : "plan-group-descriptor-001"}] + FallbackConfigurationDescriptor: + type: object + required: + - configurationContentType + - planConfig + properties: + id: + type: string + description: Unique id of the fallback configuration descriptor + example: "fallback-001" + name: + type: string + description: Descriptive name of the fallback configuration descriptor + example: "Fallback-Rollout-5G-Dublin-East" + version: + type: string + description: The version of the fallback configuration. Its format is implementation specific. + example: 1.0.0 + description: + type: string + description: Used to describe the purpose of the fallback configuration + example: "Fallback for configuration plan Rollout-5G-Dublin-East." + customProperties: + type: object + description: A dynamic set of custom properties provided by client + additionalProperties: true + example: + technology-type: NR + location: Dublin + activationJob: + type: string + description: The identifier of the related activation job. + configurationContentType: + type: string + enum: + - application/vnd.3gpp.json-patch+json + - application/vnd.3gpp.yang-patch+json + description: The format/type of the configuration in planConfig + example: "application/vnd.3gpp.yang-patch+json" + planConfig: + description: "The fallback configuration." + oneOf: + - type: string + - type: object + additionalProperties: + $ref: '#/components/schemas/Change' + description: A map of changes. The key of the map shall have the same value as the changeId. + FallbackConfigurationDescriptorResponse: + type: object + required: + - id + - configurationContentType + - planConfig + allOf: + - $ref: '#/components/schemas/FallbackConfigurationDescriptor' + properties: + _links: + type: object + description: Hypermedia links for fallback descriptor + allOf: + - $ref: '#/components/schemas/SelfLink' + example: + self: + href: "{root-url}/ProvMnS/v1/fallback-descriptors/pd-001" + templated: true + type: "application/json" + title: "The newly created FallbackConfigurationDescriptor" PlanConfigurationGroupDescriptorResponse: type: object required: - id - - applyMode + - activationMode - validationState - isOrdered - isFailOnMemberConflicts @@ -1260,7 +1394,7 @@ components: location: Dublin conditionExpression: type: string - description: The condition expression ##EDITOR JEX on NRM - OPEN + description: The condition expression ##BALAZS JEX on NRM - OPEN activationJobs: type: array items: @@ -1374,16 +1508,10 @@ components: - id - name - jobState - - PlanActivationJob: - type: object - allOf: - - $ref: '#/components/schemas/JobState' + + ActivationJobRequest: + type: object properties: - id: - type: string - description: id of the activation job - example: "job-id-3985199134" name: type: string description: Name of the activation job @@ -1392,10 +1520,11 @@ components: type: string description: Human-readable description of the job example: "Optimize the Dublin area network" - createdFallbackConfigDescrId: ##EDITOR is the name OK ? - type: string - description: Id of the created Fallback Plan Configuration Descriptor - example: "fallback-plan-descriptor-001" + mnsConsumerId: + type: array + description: The user 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 isFallbackEnabled: type: boolean description: Whether fallback should be enabled for this job @@ -1407,55 +1536,20 @@ components: default: "SHORTEST_TIME" isImmediateActivation: type: boolean - description: specifies if the activation job shall start immediately or, alternatively, by conditional activation. + description: Specifies if the activation job shall start immediately or, alternatively, by conditional activation. default: true - jobDetails: - allOf: - - $ref: '#/components/schemas/JobDetails' - jobState: - allOf: - - $ref: '#/components/schemas/JobState' - activationState: - allOf: - - $ref: '#/components/schemas/ActivationState' - activationDetails: - allOf: - - $ref: '#/components/schemas/LinkObject' - - type: object - properties: - href: - type: string - title: A URI reference to the activation details - example: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/activation-details" ##EDITOR: Why do we force the user to ask for the details in a separate request? - title: ##EDITOR at least the summary should be prsent here. - type: string - enum: - - "Link to the activation details" - method: - type: string - enum: - - "GET" - type: - type: string - description: The content type expected when following this link (MIME type). - default: "application/json" - sourceIdentity: - type: array - description: The user 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 oneOf: - - type: object + - type: object # Alt.1 planConfigDescrId required: - - planConfigDescrId # Alt.1 planConfigDescrId + - planConfigDescrId properties: planConfigDescrId: type: string description: Unique id reference to the plan descriptor to activate example: "planxyz" - - type: object + - type: object # Alt.2 planConfigDescr embedded required: - - planConfigDescr # Alt.2 planConfigDescr embedded + - planConfigDescr properties: planConfigDescr: type: object @@ -1464,14 +1558,14 @@ components: - $ref: '#/components/schemas/PlanConfigurationDescriptor' example: name: "myjob-111" - applyMode: "BEST_EFFORT" + activationMode: "BEST_EFFORT" customProperties: { techology-type: "NR", indoor: false } planConfig: ... - - type: object + - type: object # Alt.3 planConfigGroupDescrId required: - planConfigGroupDescrId # Alt.3 planConfigGroupDescrId properties: @@ -1479,168 +1573,179 @@ components: type: string description: Unique id reference to the plan group descriptor to activate example: "plan-group-xyz" - - type: object + - type: object # Alt.4 planConfigGroupDescr embedded required: - - planConfigGroupDescr # Alt.4 planConfigGroupDescr embedded + - planConfigGroupDescr properties: planConfigGroupDescr: type: string description: Inline plan group descriptor to activate allOf: - $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' - ##EDITOR Alt5. fallbackdescriptorId missing - example: - { - id : "myjob-111", - name : "5G-Dublin-East-Rollout", - description : "Optimize the 5G network in Dublin East", - isFallbackEnabled : true, - serviceImpact : "SHORTEST_TIME", - isImmediateActivation : true, - jobState : "CREATED", - jobDetails : "", - startedAt : "", - activationState : "NOT_STARTED", - activationDetails : { - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/activation-details", - templated: true, - type: "application/json", - title: "The activation details of the plan configuration(s)", - method : "GET" - }, - planConfigDescrId : "plan-descriptor-001", - } - additionalProperties : true - - PlanActivationJobRequest: - type: object - allOf: - - $ref: '#/components/schemas/PlanActivationJob' - example: - { - "name" : "5G-Dublin-East-Rollout", - "description" : "Optimize the 5G network in Dublin East", - "planConfigDescr" : { - "applyMode" : "ATOMIC", - "customProperties" : { - "technology-type": "NR", - "location": "Dublin" - }, - "planConfigContentType" : "application/vnd.3gpp.yang-patch+json", - "planConfig": { - ... - } - } - } + - type: object # Alt.5 fallbackConfigDescrId + required: + - fallbackConfigDescrId + properties: + fallbackConfigDescrId: + type: string + description: Unique id reference to the fallback descriptor to activate + example: "planxyz" + - PlanActivationJobResponse: + ActivationJob: type: object required: - id - - jobState - - jobDetails - - activationState - - activationDetails + - status - isImmediateActivation - isFallbackEnabled - serviceImpact + - jobDetails + - _links + description: An object representing a plan activation job. allOf: - - $ref: '#/components/schemas/PlanActivationJob' - properties: - _links: - description: Hypermedia links for this resource, including fixed and dynamic relations - allOf: - - $ref: '#/components/schemas/JobLinks' - - type: object - properties: - self: - allOf: - - $ref: '#/components/schemas/LinkObject' ##EDITOR Any other link will conform to LinkObject schema but we shall specify which links to expect - - type: object - properties: - href: - type: string - default: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/{planActivationJobId}" - title: - type: string - enum: - - "Link to the plan activation job" - method: - type: string - enum: - - "GET" - example: - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/activation-job-001" - title: "Link to the plan activation job" - type: "application/json" - templated: true - method: GET - fallback: - allOf: - - $ref: '#/components/schemas/LinkObject' - description: A URI reference to the fallback plan descriptor - example: - href: "{apiRoot}/ProvMnS/v1/plan-descriptor/myjob-111-fallback" - templated: true - type: "application/json" - title: "A URI reference to the fallback plan descriptor" - method: GET - ##EDITOR other links are missing. We have more in the examples -> additionalProperties to allow any other dynamic links - additionalProperties: - $ref: '#/components/schemas/LinkObject' - example: - self: - href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111" - templated: true - type: "application/json" - title: "The newly created activation job" - method : "GET" - planDescriptor: - href: "{apiRoot}/ProvMnS/v1/plan-descriptors/planxyz" - templated: true - type: "application/json" - title: "plan descriptor link" - method : "GET" + - type: object + properties: + id: + type: string + description: ID of the activation job. + example: "job-id-3985199134" status: - href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111/status" - templated: true - type: "application/json" - title: "activation status link" - method : "GET" - cancel: - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/status/jos-state" - templated: true - type: "application/json" - title: "cancel the job" - method : "PUT" - fallbackPlan: - href: "{apiRoot}/ProvMnS/v1/plan-descriptors/myfallback-plan-111" - templated: true - type: "application/json" - title: "fallback plan descriptor link" - method : "GET" + $ref: '#/components/schemas/ActivationJobStatus' + jobDetails: + $ref: '#/components/schemas/JobDetails' + activationDetails: + allOf: + - $ref: '#/components/schemas/LinkObject' + - type: object + properties: + href: + type: string + description: A URI reference to the activation details. + example: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/activation-details" + title: + type: string + enum: + - "Link to the activation details" + method: + type: string + enum: + - "GET" + type: + type: string + description: The content type expected when following this link (MIME type). + default: "application/json" + mnsConsumerId: + type: array + description: The user that created and/or started the job. It may indicate a human user and/or one or more applications initiating the job. E.g. ["userid:janedoe", "appid:12314"]. + items: + type: string + _links: + description: Hypermedia links for this resource, including fixed and dynamic relations. + allOf: + - $ref: '#/components/schemas/JobLinks' + - type: object + properties: + self: + allOf: + - $ref: '#/components/schemas/LinkObject' + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/activation-jobs/{ActivationJobId}" + title: + type: string + enum: + - "Link to the plan activation job" + method: + type: string + enum: + - "GET" + example: + href: "{apiRoot}/ProvMnS/v1/activation-jobs/activation-job-001" + title: "Link to the plan activation job" + type: "application/json" + templated: true + method: "GET" + fallback: + allOf: + - $ref: '#/components/schemas/LinkObject' + - type: object + description: A URI reference to the fallback plan descriptor. + example: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/myjob-111-fallback" + templated: true + type: "application/json" + title: "A URI reference to the fallback plan descriptor" + method: "GET" + additionalProperties: + $ref: '#/components/schemas/LinkObject' + - $ref: '#/components/schemas/ActivationJobRequest' + example: + id: "myjob-111" + name: "5G-Dublin-East-Rollout" + description: "Optimize the 5G network in Dublin East" + isFallbackEnabled: true + serviceImpact: "SHORTEST_TIME" + isImmediateActivation: true + status: + jobState: "RUNNING" + startedAt: "" + activationState: "NOT_STARTED" + jobDetails: {} # Assuming this is a simple object + activationDetails: + href: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/activation-details" + templated: true + type: "application/json" + title: "The activation details of the plan configuration(s)" + method: "GET" + planConfigDescrId: "plan-descriptor-001" + _links: + self: + href: "{apiRoot}/ProvMnS/1900/activation-jobs/myjob-111" + templated: true + type: "application/json" + title: "The newly created activation job" + method: "GET" + planDescriptor: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/planxyz" + templated: true + type: "application/json" + title: "plan descriptor link" + method: "GET" + status: + href: "{apiRoot}/ProvMnS/1900/activation-jobs/myjob-111/status" + templated: true + type: "application/json" + title: "activation status link" + method: "GET" + activation-details: + href: "{apiRoot}/ProvMnS/1900/activation-jobs/myjob-111/activation-details" + templated: true + type: "application/json" + title: "activation details link" + method: "GET" + cancel: + href: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/cancel-request" + templated: true + type: "application/json" + title: "cancel the job" + method: "PUT" + fallbackPlan: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/myfallback-plan-111" + templated: true + type: "application/json" + title: "fallback plan descriptor link" + method: "GET" + additionalProperties: true - CancelRequest: - type: object - required: - - jobState - properties: - jobState: - type: string - enum : - - CANCELLING - description: set to CANCELLING to cancel a job - example: CANCELLING - - PlanValidationJob: + ValidationJobRequest: type: object - allOf: - - $ref: '#/components/schemas/JobState' + required: + - _links + description: An object representing a plan activation job. properties: - id: - type: string - description: id of the validation job - example: "job-id-3985199134" name: type: string description: Name of the validation job @@ -1649,86 +1754,203 @@ components: type: string description: Human-readable description of the job example: "Optimize the Dublin area network" - jobDetails: - allOf: - - $ref: '#/components/schemas/JobDetails' - jobState: - allOf: - - $ref: '#/components/schemas/JobState' - validationState: - allOf: - - $ref: '#/components/schemas/ValidationState' - validationDetails: - allOf: - - $ref: '#/components/schemas/LinkObject' - - type: object - properties: - href: - type: string - title: A URI reference to the validation details - example: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/validation-details" - title: - type: string - enum: - - "Link to the validation details" - method: - type: string - enum: - - "GET" - type: - type: string - description: The content type expected when following this link (MIME type). - default: "application/json" - sourceIdentity: + validationMode: + type: string + enum: [CONTINUE_ON_ERROR, STOP_ON_ERROR] + default : "CONTINUE_ON_ERROR" + description: Specifies the execution behavior when the plan is activated + mnsConsumerId: type: array description: The user 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 oneOf: - - type: object + - type: object # Alt.1 planConfigDescrId required: - - planConfigDescrId # Alt.1 planConfigDescrId + - planConfigDescrId properties: planConfigDescrId: type: string - description: Unique id reference to the plan descriptor to activate + description: Unique id reference to the plan descriptor to validate example: "planxyz" - - type: object + - type: object # Alt.2 planConfigDescr embedded required: - - planConfigDescr # Alt.2 planConfigDescr embedded + - planConfigDescr properties: planConfigDescr: type: object - description: Inline plan configuration descriptor to activate + description: Inline plan configuration descriptor to validate allOf: - $ref: '#/components/schemas/PlanConfigurationDescriptor' example: name: "myjob-111" - applyMode: "BEST_EFFORT" + activationMode: "BEST_EFFORT" customProperties: { techology-type: "NR", indoor: false } planConfig: ... - - type: object + - type: object # Alt.3 planConfigGroupDescrId required: - - planConfigGroupDescrId # Alt.3 planConfigGroupDescrId + - planConfigGroupDescrId properties: planConfigGroupDescrId: type: string - description: Unique id reference to the plan group descriptor to activate + description: Unique id reference to the plan group descriptor to validate example: "plan-group-xyz" - - type: object + - type: object # Alt.4 planConfigGroupDescr embedded required: - - planConfigGroupDescr # Alt.4 planConfigGroupDescr embedded + - planConfigGroupDescr properties: planConfigGroupDescr: type: string - description: Inline plan group descriptor to activate + description: Inline plan group descriptor to validate allOf: - $ref: '#/components/schemas/PlanConfigurationGroupDescriptor' - ##EDITOR ALt.5 fallback missing + - type: object # Alt.5 fallbackConfigDescrId + required: + - fallbackConfigDescrId + properties: + fallbackConfigDescrId: + type: string + description: Unique id reference to the fallback descriptor to validate + example: "planxyz" + example: + { + name : "5G-Dublin-East-Rollout", + description : "Optimize the 5G network in Dublin East", + planConfigDescrId : "plan-descriptor-001", + } + additionalProperties : true + + ValidationJob: + type: object + required: + - id + - status + - jobDetails + - validationDetails + - _links + allOf: + - $ref: '#/components/schemas/ValidationJobRequest' + - type: object + properties: + id: + type: string + description: id of the validation job + example: "job-id-3985199134" + status: + allOf: + - $ref: '#/components/schemas/ValidationJobStatus' + jobDetails: + allOf: + - $ref: '#/components/schemas/JobDetails' + validationDetails: + allOf: + - $ref: '#/components/schemas/LinkObject' + - type: object + properties: + href: + type: string + title: A URI reference to the validation details + example: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/validation-details" + title: + type: string + enum: + - "Link to the validation details" + method: + type: string + enum: + - "GET" + type: + type: string + description: The content type expected when following this link (MIME type). + default: "application/json" + _links: + description: Hypermedia links for this resource, including fixed and dynamic relations + allOf: + - $ref: '#/components/schemas/JobLinks' + - type: object + properties: + self: + allOf: + - $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/validation-jobs/{validationJobId}" + title: + type: string + enum: + - "Link to the plan validation job" + method: + type: string + enum: + - "GET" # This means the method MUST be "GET" + example: + href: "{apiRoot}/ProvMnS/v1/validation-jobs/validation-job-001" + title: "Link to the plan validation job" + type: "application/json" + templated: true + method: GET + cencel: + allOf: + - $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema + - type: object + properties: + href: + type: string + default: "{apiRoot}/ProvMnS/v1/validation-jobs/{validationJobId}/status" + title: + type: string + enum: + - "Link to the plan validation job" + method: + type: string + enum: + - "PATCH" # This means the method MUST be "GET" + example: + href: "{apiRoot}/ProvMnS/v1/validation-jobs/validation-job-001/status" + title: "Link to the cancel validation job - cancelRequest : true must be in body" + type: "application/json" + templated: true + method: PUT + + + required : + - self + - cancel + # additionalProperties to allow any other dynamic links + additionalProperties: + $ref: '#/components/schemas/LinkObject' + example: + self: + href: "{apiRoot}/ProvMnS/1900/activation-jobs/myjob-111" + templated: true + type: "application/json" + title: "The newly created activation job" + method : "GET" + planDescriptor: + href: "{apiRoot}/ProvMnS/v1/plan-descriptors/planxyz" + templated: true + type: "application/json" + title: "plan descriptor link" + method : "GET" + status: + href: "{apiRoot}/ProvMnS/1900/activation-jobs/myjob-111/status" + templated: true + type: "application/json" + title: "activation status link" + method : "GET" + cancel: + href: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/status" + templated: true + type: "application/json" + title: "cancel the job" + method : "PATCH" + example: { id : "myjob-111", @@ -1737,121 +1959,41 @@ components: isFallbackEnabled : true, serviceImpact : "SHORTEST_TIME", isImmediateActivation : true, - jobState : "CREATED", - jobDetails : "", - startedAt : "", - activationState : "NOT_STARTED", - activationDetails : { - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/activation-details", + status : { + jobState : "RUNNING", + jobDetails : {...}, + startedAt : "", + activationState : "NOT_STARTED" + }, + validationDetails : { + href: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/validation-details", templated: true, type: "application/json", - title: "The activation details of the plan configuration(s)", + title: "The validation details of the plan configuration(s)", method : "GET" }, planConfigDescrId : "plan-descriptor-001", } additionalProperties : true - - PlanValidationJobRequest: - type: object - allOf: - - $ref: '#/components/schemas/PlanValidationJob' - example: - { - "name" : "5G-Dublin-East-Rollout", - "description" : "Optimize the 5G network in Dublin East", - "planDescriptor" : { - "applyMode" : "ATOMIC", - "customProperties" : { - "technology-type": "NR", - "location": "Dublin" - }, - "planConfig": { - ... - } - } - } - PlanValidationJobResponse: - type: object - required: - - id - - jobState - - jobDetails - - validationState - - validationDetails - allOf: - - $ref: '#/components/schemas/PlanValidationJob' + CancelRequest: + type: object properties: - _links: - description: Hypermedia links for this resource, including fixed and dynamic relations - allOf: - - $ref: '#/components/schemas/JobLinks' - - type: object - properties: - self: - allOf: - - $ref: '#/components/schemas/LinkObject' # Any other link will conform to LinkObject schema - - type: object - properties: - href: - type: string - default: "{apiRoot}/ProvMnS/v1/plan-validation-jobs/{planValidationJobId}" - title: - type: string - enum: - - "Link to the plan validation job" - method: - type: string - enum: - - "GET" # This means the method MUST be "GET" - example: - href: "{apiRoot}/ProvMnS/v1/plan-validation-jobs/validation-job-001" - title: "Link to the plan validation job" - type: "application/json" - templated: true - method: GET - # additionalProperties to allow any other dynamic links - additionalProperties: - $ref: '#/components/schemas/LinkObject' - example: - self: - href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111" - templated: true - type: "application/json" - title: "The newly created activation job" - method : "GET" - planDescriptor: - href: "{apiRoot}/ProvMnS/v1/plan-descriptors/planxyz" - templated: true - type: "application/json" - title: "plan descriptor link" - method : "GET" - status: - href: "{apiRoot}/ProvMnS/1900/plan-activation-jobs/myjob-111/status" - templated: true - type: "application/json" - title: "activation status link" - method : "GET" - cancel: - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/cancel" - templated: true - type: "application/json" - title: "cancel the job" - method : "POST" - fallbackPlan: - href: "{apiRoot}/ProvMnS/v1/plan-descriptors/myfallback-plan-111" - templated: true - type: "application/json" - title: "fallback plan descriptor link" - method : "GET" - - AbstractChangeDefinition: + cancelRequest: + type: boolean + description: property to cancel the activation/validation job + example: true + + Change: type: object properties: + changeId: + type: string + description: Unique identifier for this change + example: "opId-001" operation: type: string - enum: [create, merge, update, remove] + enum: [create, merge, update, delete] description: The operation to perform example: "create" description: @@ -1865,18 +2007,8 @@ components: value: type: object additionalProperties: true # Allows any nested properties within 'value' - description: Value to apply (for create/merge/remove operations) - - Change: - allOf: - - $ref: '#/components/schemas/AbstractChangeDefinition' - - type: object - properties: - changeId: - type: string - description: Unique identifier for this change - example: "opId-001" - additionalProperties: true # Allows any nested properties within 'value' + description: Value to apply (for create/update/merge/delete operations) + additionalProperties: true # Allows for any nested properties required: - operation - target @@ -1916,7 +2048,7 @@ components: properties: href: type: string - default: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/{jobId}/status" + default: "{apiRoot}/ProvMnS/v1/activation-jobs/{jobId}/status" title: type: string enum: @@ -1927,7 +2059,7 @@ components: - "GET" # This means the method MUST be "GET" description: A URI reference to the status information example: - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/status" + href: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/status" title: "Link to GET the job status" type: "application/json" templated: true @@ -1939,7 +2071,7 @@ components: properties: href: type: string - default: "{apiRoot}/ProvMnS/v1/plan-{job-type}-jobs/{jobId}/status/job-state" + default: "{apiRoot}/ProvMnS/v1/plan-{job-type}-jobs/{jobId}/status" title: type: string enum: @@ -1947,18 +2079,18 @@ components: method: type: string enum: - - "PUT" # This means the method MUST be "PUT" + - "PATCH" # This means the method MUST be "PATCH" description: A URI reference to cancel the job example: - href: "{apiRoot}/ProvMnS/v1/plan-activation-jobs/myjob-111/cancel" + href: "{apiRoot}/ProvMnS/v1/activation-jobs/myjob-111/status" title: "Link to cancel the job" type: "application/json" templated: true - method: POST + method: PATCH JobState: type: string - enum: [CREATED, RUNNING, COMPLETED, FAILED, CANCELLING, CANCELLED] + enum: [NOT_STARTED, QUEUED, RUNNING, CANCELLING, CANCELLED, COMPLETED, FAILED] example: "COMPLETED" JobDetails: @@ -2017,7 +2149,7 @@ components: planDescriptorId: type: string example: "planconfig-descriptor-001" - changes: ##EDITOR format is TBD + changes: type: array items: $ref: '#/components/schemas/ChangeStatus' @@ -2025,7 +2157,7 @@ components: $ref: '#/components/schemas/SummaryStatus' example: { - "results": { ...}, ##EDITOR format is TBD + "results": { ...}, "summary" : { "unprocessed": 0, "succeeded": 2, @@ -2035,7 +2167,7 @@ components: ValidationState: type: string - enum: [NOT_VALIDATED, VALIDATING, VALIDATED, VALIDATION_FAILED, PARTIALLY_VALIDATED] + enum: [UNKNOWN, VALIDATION_SUCCEEDED, VALIDATION_FAILED] example: "VALIDATED" ActivationState: @@ -2051,8 +2183,8 @@ components: example: "changeId-001" state: type: string - enum: [SUCCEEDED, FAILED, UNPROCESSED] - default: UNPROCESSED + enum: [NOT_STARTED, PROCESSING, SUCCEEDED, FAILED] + default: NOT_STARTED example: "SUCCEEDED" target: type: string @@ -2066,7 +2198,7 @@ components: items: $ref: '#/components/schemas/Conflict' required: - - changeId ##EDITOR yes or no + - changeId # either the changeId from the plan or the array index in the array of Change; - target - state example: @@ -2087,7 +2219,7 @@ components: SummaryStatus: type: object properties: - unprocessed: + notFinished: type: integer example: 1 succeeded: @@ -2108,7 +2240,7 @@ components: allOf: - $ref: '#/components/schemas/Change' properties: - planDescriptorId: ##EDITOR if missing the conlict is in same plan config descriptor as the 'source' change -> comment to be added in description + planDescriptorId: type: string change: $ref: '#/components/schemas/Change' @@ -2150,7 +2282,7 @@ components: ConflictingChange: type: object properties: - planDescriptorId: ##EDITOR if missing the conlict is in same plan config descriptor as the 'source' change -> to add to description + planDescriptorId: type: string change: $ref: '#/components/schemas/Change' @@ -2452,7 +2584,7 @@ components: UpdateNrCellChange: summary: Update an existing NR Cell (merge operation) value: - operation: merge + operation: update changeId: update-nr-cell-002 description: Update administrativeState for existing NRCellDU=1. target: /_3gpp-common-subnetwork:SubNetwork=North/_3gpp-common-mecontext:MeContext=Dublin-1/_3gpp_nrm_managedelement:ManagedElement=ENB-A/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1/_3gpp_nrm_nrcelldu:NRCellDU=1 @@ -2461,7 +2593,7 @@ components: RemoveNrCellChange: summary: Remove an NR Cell (remove operation) value: - operation: remove + operation: delete changeId: remove-nr-cell-003 description: Decommission NRCellDU=3. target: /_3gpp-common-subnetwork:SubNetwork=Irl/_3gpp-common-mecontext:MeContext=Dublin-1/_3gpp_nrm_managedelement:ManagedElement=1/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1/_3gpp_nrm_nrcelldu:NRCellDU=3 \ No newline at end of file -- GitLab From 6504a5be642a1e56d5eccb8a7172d9549ab6172d Mon Sep 17 00:00:00 2001 From: lengyelb Date: Wed, 27 Aug 2025 00:45:56 +0200 Subject: [PATCH 4/4] Edit TS28572_PlanManagement.yaml added currentConfigTime --- OpenAPI/TS28572_PlanManagement.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/OpenAPI/TS28572_PlanManagement.yaml b/OpenAPI/TS28572_PlanManagement.yaml index b1ec7c8cf..3d33a9a65 100644 --- a/OpenAPI/TS28572_PlanManagement.yaml +++ b/OpenAPI/TS28572_PlanManagement.yaml @@ -1846,6 +1846,9 @@ components: jobDetails: allOf: - $ref: '#/components/schemas/JobDetails' + currentConfigTime: + type: string + format: date-time validationDetails: allOf: - $ref: '#/components/schemas/LinkObject' -- GitLab