MEF LSO Cantata Circuit Impairment and Maintenance

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