MEF Circuit Impairment and Maintenance (Mef Lso Cantata Circuit Impairment And Maintenance)
MEF Circuit Impairment and Maintenance from MEF — 4 path(s) described in OpenAPI.
OpenAPI Specification
openapi: 3.0.1
info:
title: Circuit Impairment and Maintenance
description: >
**This file forms part of Mplify 175**
This API implements Business Requirements described in Mplify 113 and 173
It allows the Buyer to retrieve CIM Incident as well as register for event
notifications
related to CIM Incidents. The CIM Incident is a record of a Circuit
Impairment
that has been reported by the Buyer to the Seller, or that has been
identified
by the Seller, and that is being tracked by the Seller until it is resolved.
List of supported use cases:
- Retrieve CIM Incident List
- Retrieve CIM Incident by CIM Incident Identifier
- Register for Event Notifications
Copyright 2025 Mplify Alliance and its contributors
This file includes content based on the TM Forum Trouble Ticket API (TMF621
v4.0.0) available at https://github.com/tmforum-apis/TMF621_TroubleTicket,
which is licensed by the TM Forum under the Apache License version 2.0.
Such content has been modified by the Mplify Alliance and its contributors.
version: 1.0.0
servers:
- url: 'https://{serverBase}/mefApi/cantata/cimIncident/v1/'
variables:
serverBase:
description: The base of Seller's URL.
default: mef.net
tags:
- name: CIM Incident
- name: events subscription
paths:
/cimIncident:
get:
tags:
- CIM Incident
summary: List or found CIM Incident objects
description: >
The Buyer requests a list of CIM Incidents from the Seller based on a
set of specified filter criteria. The Seller returns a summarized list
of CIM Incidents.
operationId: listCimIncident
parameters:
- name: priority
in: query
description: >-
The priority (ITIL) is based on the assessment of the impact and
urgency of how quickly the CIM Incident should be resolved after
evaluation by the Seller of the impact of the CIM Incident.
required: false
schema:
$ref: '#/components/schemas/CimIncidentPriorityType'
- name: severity
in: query
description: >-
The severity or impact (ITIL) of the CIM Incident as evaluated by
the Seller.
required: false
schema:
$ref: '#/components/schemas/CimIncidentSeverityType'
- name: impact
in: query
description: The type of impact observed by the Buyer.
required: false
schema:
$ref: '#/components/schemas/MEFObservedImpactType'
- name: incidentType
in: query
description:
The presumed cause of the CIM Incident as evaluated by the Seller.
required: false
schema:
$ref: '#/components/schemas/CimIncidentType'
- name: status
in: query
description: The current status of the CIM Incident
required: false
schema:
$ref: '#/components/schemas/IncidentStatusType'
- name: relatedEntityId
in: query
description: >-
ID of a related entity that this CIM Incident is related to and is
present in the `relatedEntity` list
required: false
schema:
type: string
- name: relatedEntityType
in: query
description: >-
Type of a related entity that this CIM Incident is related to and is
present in the `relatedEntity` list
required: false
schema:
type: string
default: Product
- name: creationDate.gt
in: query
description:
The date on which the CIM Incident was created - greater than
required: false
schema:
type: string
format: date-time
- name: creationDate.lt
in: query
description: The date on which CIM Incident was created - lower than
required: false
schema:
type: string
format: date-time
- name: situationStartDate.gt
in: query
description: >-
The date when the CIM Incident was first identified, for example via
error logs - greater than
required: false
schema:
type: string
format: date-time
- name: situationStartDate.lt
in: query
description: >-
The date when the CIM Incident was first identified, for example via
error logs - lower than
required: false
schema:
type: string
format: date-time
- name: expectedClosedDate.gt
in: query
description: >-
The date provided by the Seller to indicate when the CIM Incident is
expected to be closed - greater than
required: false
schema:
type: string
format: date-time
- name: expectedClosedDate.lt
in: query
description: >-
The date provided by the Seller to indicate when the CIM Incident is
expected to be closed - lower than
required: false
schema:
type: string
format: date-time
- name: closedDate.gt
in: query
description: >-
The date the CIM Incident status was set to closed by the Seller -
greater than
required: false
schema:
type: string
format: date-time
- name: closedDate.lt
in: query
description: >-
The date the CIM Incident status was set to closed by the Seller -
lower than
required: false
schema:
type: string
format: date-time
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
- name: offset
in: query
description:
Requested index for start of resources to be provided in response
required: false
schema:
type: integer
- name: limit
in: query
description: Requested number of resources to be provided in response
required: false
schema:
type: integer
format: int32
responses:
'200':
description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
headers:
X-Pagination-Throttled:
description: >
Used to indicate that result page was throttled to maximum
possible size and there are additional results that can be
fetched
schema:
type: boolean
X-Total-Count:
description: >
The total number of matching records. E.g. if there are 50
matching records in total, but the request has offset=10 and
limit=10, then the X-Total-Count is 50.
schema:
type: integer
X-Result-Count:
description: The number of records included in the response
schema:
type: integer
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/CimIncident'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description: Unprocessable entity due to business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'/cimIncident/{id}':
get:
tags:
- CIM Incident
summary: Retrieves ac CIM Incident by ID
description: >-
The Buyer requests detailed information about a single CIM Incident
based on a CIM Incident Identifier.
operationId: retrieveCimIncident
parameters:
- name: id
in: path
description: Identifier of the CIM Incident
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
responses:
'200':
description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/CimIncident'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
/hub:
post:
tags:
- events subscription
summary:
Allows the Buyer to register to CIM Incident status change notifications
description:
The Buyer requests to subscribe to CIM Incident Notifications.
operationId: registerListener
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description:
Data containing the callback endpoint to deliver the information
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscriptionInput'
required: true
responses:
'201':
description:
'Subscribed (https://tools.ietf.org/html/rfc7231#section-6.3.2)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscription'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
'/hub/{id}':
get:
tags:
- events subscription
summary: Retrieves listener information
description: This operation retrieves a hub entity.
operationId: retrieveHub
parameters:
- name: id
in: path
description: Identifier of the Hub
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding
entity represents more than one Seller.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscription'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: Method not implemented.
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
delete:
tags:
- events subscription
summary: Unregister a listener
description:
The Buyer requests to unsubscribe from CIM Incident Notifications
operationId: unregisterListener
parameters:
- name: id
in: path
description: The id of the EventSubscription
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
responses:
'204':
description:
'Deleted (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
'400':
description: Bad request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'501':
description: >-
Method not implemented. Used in case Seller is not supporting
Notification mechanism
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error501'
components:
schemas:
AttachmentValue:
description: >-
Complements the description of an element (for instance a product)
through video, pictures...
type: object
properties:
author:
description:
The name of the person or organization who added the Attachment.
type: string
creationDate:
description: The date the Attachment was added.
type: string
format: date-time
description:
description: A narrative text describing the content of the attachment
type: string
mimeType:
description: >-
Attachment mime type such as extension file for video, picture and
document
type: string
name:
description: The name of the attachment
type: string
size:
description: The size of the attachment.
$ref: '#/components/schemas/MEFByteSize'
source:
description:
Indicates if the attachment was added by the Buyer or the Seller.
$ref: '#/components/schemas/MEFBuyerSellerType'
url:
description: URL where the attachment is located.
type: string
required:
- author
- creationDate
- name
- source
- url
CimFailureIncident:
description: >-
Sent when the Seller detects an occurrence of a Situation on a Product
provided to the Buyer, where the Product is non-operational (for
example, down, routing failures, severe packet drops, etc.).
allOf:
- $ref: '#/components/schemas/CimIncident'
- type: object
properties:
'@type':
description: >-
Used to unambiguously designate the class type when using
`oneOf`
type: string
enum:
- CimFailureIncident
impact:
description:
The presumed impact on the Buyer for the referenced Product(s).
type: string
enum:
- down
incidentType:
description: >-
The presumed cause of the CIM Incident as evaluated by the
Seller.
type: string
enum:
- failure
CimIncident:
description: >
An CIM Incident is a record of an issue that is not part of normal
operation in the Seller's network that has a possible negative impact on
the operability of the network on one or more Buyers.
type: object
properties:
'@type':
description:
Used to unambiguously designate the class type when sub-classing
type: string
attachment:
description: >-
Attachments to the Incident, such as a file or screenshot.
Attachments may be added but may not be modified or deleted (for
historical reasons).
type: array
items:
$ref: '#/components/schemas/AttachmentValue'
closedDate:
description:
The date the CIM Incident status was set to closed by the Seller
type: string
format: date-time
creationDate:
description: The date on which the CIM Incident was created
type: string
format: date-time
description:
description: Description of the CIM Incident
type: string
expectedClosedDate:
description: >-
The date provided by the Seller to indicate when the CIM Incident is
expected to be closed.
type: string
format: date-time
href:
description: 'Hyperlink, a reference to the CIM Incident entity'
type: string
id:
description:
Unique (within the Seller domain) identifier for the CIM Incident.
type: string
impact:
description:
The presumed impact on the Buyer for the referenced Product(s).
type: string
incidentType:
description:
The presumed cause of the CIM Incident as evaluated by the Seller.
type: string
note:
description: >-
A set of unstructured comments or information associated to the CIM
Incident. Notes may be added but may not be modified or deleted (for
historical reasons).
type: array
items:
$ref: '#/components/schemas/Note'
priority:
description: >-
The priority (ITIL) is based on the assessment of the impact and
urgency of how quickly the CIM Incident should be resolved after
evaluation by the Seller of the impact of the CIM Incident.
$ref: '#/components/schemas/CimIncidentPriorityType'
relatedContactInformation:
description: >-
Party playing a role in this CIM Incident.
The 'role' is to specify the type of contact as specified in MEF
113:
Incident Contact ('role=incidentContact') - REQUIRED to be set by
the Seller
Incident Technical Contact ('role=incidentTechnicalContact')
type: array
minItems: 1
items:
$ref: '#/components/schemas/RelatedContactInformation'
relatedEntity:
description: >-
A set of identifiers of the Products on which the CIM Incident could
have an impact on the normal operation.
type: array
minItems: 1
items:
$ref: '#/components/schemas/RelatedEntity'
relatedIssue:
description: >-
A list of Issue Relationships. Represents relationships to other
Trouble Tickets, Incidents, and CIM Incidents.
type: array
items:
$ref: '#/components/schemas/IssueRelationship'
severity:
description:
The severity (ITIL) of the CIM Incident as evaluated by the Seller.
$ref: '#/components/schemas/CimIncidentSeverityType'
situationStartDate:
description: >-
The date when the situation was first identified, for example via
error logs.
type: string
format: date-time
status:
description: The current status of the CIM Incident
$ref: '#/components/schemas/IncidentStatusType'
statusChange:
description: >-
The status change history that is associated to the CIM Incident.
Populated by the Seller.
type: array
minItems: 1
items:
$ref: '#/components/schemas/IncidentStatusChange'
required:
- '@type'
- creationDate
- description
- id
- impact
- incidentType
- priority
- relatedContactInformation
- relatedEntity
- severity
- situationStartDate
- status
- statusChange
discriminator:
propertyName: '@type'
mapping:
CimFailureIncident: '#/components/schemas/CimFailureIncident'
CimServiceImpairmentIncident: '#/components/schemas/CimServiceImpairmentIncident'
CimMaintenanceIncident: '#/components/schemas/CimMaintenanceIncident'
oneOf:
- $ref: '#/components/schemas/CimFailureIncident'
- $ref: '#/components/schemas/CimServiceImpairmentIncident'
- $ref: '#/components/schemas/CimMaintenanceIncident'
CimIncidentPriorityType:
description: Possible values for the priority of CIM Incident
type: string
enum:
- low
- medium
- high
- critical
CimIncidentSeverityType:
description: Possible values for the severity of CIM Incident
type: string
enum:
- minor
- moderate
- significant
- extensive
CimIncidentType:
description: >
Possible values for the type of the CIM Incident:
- congestion - Any Situation due to traffic congestion, such as
resulting in packet drops or traffic delays.
- failure - Any Situation where the Product is non-operational, such as
down, routing failures or severe packet drops.
- plannedMaintenance -Any scheduled maintenance that may impact a
Product for the Buyer.
- policing - Any Situation due to traffic violating traffic profiles
associated with the subscribed service, such as traffic drops due to
policing.
type: string
enum:
- congestion
- failure
- plannedMaintenance
- policing
CimMaintenanceIncident:
description: >-
Any scheduled maintenance to be performed by the Seller that may impact
a Product for the Buyer, which also includes the planned ending time and
date.
allOf:
- $ref: '#/components/schemas/CimIncident'
- type: object
properties:
'@type':
description: >-
Used to unambiguously designate the class type when using
`oneOf`
type: string
enum:
- CimMaintenanceIncident
impact:
description:
The presumed impact on the Buyer for the referenced Product(s).
$ref: '#/components/schemas/MEFObservedImpactType'
incidentType:
description: >-
The presumed cause of the CIM Incident as evaluated by the
Seller.
type: string
enum:
- plannedMaintenance
required:
- expectedClosedDate
CimServiceImpairmentIncident:
description: >-
Sent when the Seller detects an occurrence of a Situation on a Product
provided to the Buyer, where the Product is not meeting the Product
specifications or is not operational on an intermittent basis. This
includes impairments due to traffic violating traffic profile thresholds
(for example, excessive traffic drops due to policing) and/or traffic
congestion exceeding thresholds.
allOf:
- $ref: '#/components/schemas/CimIncident'
- type: object
properties:
'@type':
description: >-
Used to unambiguously designate the class type when using
`oneOf`
type: string
enum:
- CimServiceImpairmentIncident
impact:
description:
The presumed impact on the Buyer for the referenced Product(s).
type: string
enum:
- degraded
- intermittent
incidentType:
description: >-
The presumed cause of the CIM Incident as evaluated by the
Seller.
type: string
enum:
- policing
- congestion
DataSizeUnit:
description: The unit of measure in the data size.
type: string
enum:
- BYTES
- KBYTES
- MBYTES
- GBYTES
- TBYTES
- PBYTES
- EBYTES
- ZBYTES
- YBYTES
Error:
description: >
Standard Class used to describe API response error Not intended to be
used directly. The `code` in the HTTP header is used as a discriminator
for the type of error returned in runtime.
type: object
properties:
message:
description: >-
Text that provides mode details and corrective actions related to
the error. This can be shown to a client user.
type: string
reason:
description: >-
Text that explains the reason for the error. This can be shown to a
client user.
type: string
maxLength: 255
referenceError:
description: URL pointing to documentation describing the error
type: string
format: uri
required:
- reason
Error400:
description:
'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
code:
description: >-
One of the following error codes:
- missingQueryParameter: The URI is missing a required
query-string parameter
- missingQueryValue: The URI is missing a required query-string
parameter value
- invalidQuery: The query section of the URI is invalid.
- invalidBody: The request has an invalid body
$ref: '#/components/schemas/Error400Code'
required:
- code
Error400Code:
description: >-
One of the follow
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-cantata-circuit-impairment-and-maintenance-openapi.yml