MEF LSO Legato Service Ordering Management

openapi: 3.0.1
info:
  title: Service Ordering Management
  description: |
    **This file forms part of Mplify 99.1** 
     

    Supported use cases:
    - Create Service Order
    - Retrieve List of Service Orders
    - Retrieve Service Order by Service Order Identifier
    - Register for Notifications

    Copyright 2025 Mplify Alliance and its contributors.

    This file includes content based on the TM Forum Service Order API (TMF641
    v4.1.0) available at https://github.com/tmforum-apis/TMF641_ServiceOrder,
    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: 6.0.1
servers:
  - url: "https://{serverBase}/mefApi/legato/serviceOrderingManagement/v6/"
    variables:
      serverBase:
        description: The base of SOF's URL.
        default: mplify.net
tags:
  - name: Service Order
    description: Operations for Service Order Resource
  - name: Events subscription
    description: Endpoints to register and terminate an Event Listener
paths:
  /serviceOrder:
    get:
      tags:
        - Service Order
      summary: List or find ServiceOrder objects
      description: This operation retrieves list of ServiceOrder entities.
      operationId: listServiceOrder
      parameters:
        - name: state
          in: query
          description: State of the Service Order
          required: false
          schema:
            $ref: "#/components/schemas/ServiceOrderStateType"
        - name: orderDate.gt
          in: query
          description: Date when the order was created greater than
          required: false
          schema:
            type: string
            format: date-time
        - name: orderDate.lt
          in: query
          description: Date when the order was created lesser than
          required: false
          schema:
            type: string
            format: date-time
        - name: completionDate.gt
          in: query
          description: Effective completion date greater than
          required: false
          schema:
            type: string
            format: date-time
        - name: completionDate.lt
          in: query
          description: Effective completion date lesser than
          required: false
          schema:
            type: string
            format: date-time
        - name: expectedCompletionDate.gt
          in: query
          description: Expected delivery date greater than
          required: false
          schema:
            type: string
            format: date-time
        - name: expectedCompletionDate.lt
          in: query
          description: Expected delivery date lesser than
          required: false
          schema:
            type: string
            format: date-time
        - name: startDate.gt
          in: query
          description: Date when the order was started for processing
          required: false
          schema:
            type: string
            format: date-time
        - name: startDate.lt
          in: query
          description: Date when the order was started for processing
          required: false
          schema:
            type: string
            format: date-time
        - name: offset
          in: query
          description: >-
            Requested index for start of item to be provided in response
            requested by the client. Note that the index starts with "0".
          required: false
          schema:
            type: integer
            format: int32
        - name: limit
          in: query
          description: >-
            Requested number of items to be provided in response requested by
            client
          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 items. E.g. if there are 50
                matching items 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 items included in the response
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ServiceOrder"
        "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"
    post:
      tags:
        - Service Order
      summary: Creates a ServiceOrder
      description: This operation creates a ServiceOrder entity.
      operationId: createServiceOrder
      requestBody:
        description: The ServiceOrder to be created
        content:
          application/json;charset=utf-8:
            schema:
              $ref: "#/components/schemas/ServiceOrder_Create"
        required: true
      responses:
        "201":
          description: "Created (https://tools.ietf.org/html/rfc7231#section-6.3.2)"
          content:
            application/json;charset=utf-8:
              schema:
                $ref: "#/components/schemas/ServiceOrder"
        "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"
  "/serviceOrder/{id}":
    get:
      tags:
        - Service Order
      summary: Retrieves a ServiceOrder by ID
      description: This operation retrieves a ServiceOrder entity.
      operationId: retrieveServiceOrder
      parameters:
        - name: id
          in: path
          description: Identifier of the ServiceOrder
          required: true
          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/ServiceOrder"
        "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"
  /hub:
    post:
      tags:
        - Events subscription
      summary: Register a listener
      description: >-
        Sets the communication endpoint address the service instance must use to
        deliver information about its health state, execution state, failures
        and metrics.
      operationId: registerListener
      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
          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 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"
  "/hub/{id}":
    get:
      tags:
        - Events subscription
      summary: Retrieves a EventSubscription by ID
      description: This operation retrieves a EventSubscription entity.
      operationId: retrieveEventSubscription
      parameters:
        - name: id
          in: path
          description: Identifier of the EventSubscription
          required: true
          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"
    delete:
      tags:
        - Events subscription
      summary: Unregister a listener
      description: >-
        Resets the communication endpoint address the service instance must use
        to deliver information about its health state, execution state, failures
        and metrics.
      operationId: unregisterListener
      parameters:
        - name: id
          in: path
          description: The id of the registered listener
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "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"
        '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"
components:
  schemas:
    BusSofType:
      description: An enumeration with BUS and SOF values.
      type: string
      enum:
        - bus
        - sof
    ContactInformation:
      description: >-
        Contact data for a person or organization that is involved in the
        product offering qualification. In a given context it is always
        specified by the SOF (e.g. SOF Contact Information) or by the
        BUS.
      type: object
      properties:
        number:
          description: Phone number
          type: string
        emailAddress:
          description: Email address
          type: string
        postalAddress:
          description: >-
            Identifies the postal address of the person or office to be
            contacted.
          $ref: '#/components/schemas/FieldedAddressRepresentation'
        organization:
          description: The organization or company that the contact belongs to
          type: string
        name:
          description: Name of the contact
          type: string
        numberExtension:
          description: Phone number extension
          type: string
      required:
        - emailAddress
        - name
        - number
    Duration:
      description: 'A Duration in a given unit of time e.g. 3 hours, or 5 days.'
      type: object
      properties:
        amount:
          description: 'Duration (number of seconds, minutes, hours, etc.)'
          type: integer
          minimum: 0
        units:
          description: Time unit enumerated
          $ref: '#/components/schemas/TimeUnit'
      required:
        - amount
        - units
    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 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
      type: string
      enum:
        - missingQueryParameter
        - missingQueryValue
        - invalidQuery
        - invalidBody
    Error401:
      description: "Unauthorized.  (https://tools.ietf.org/html/rfc7235#section-3.1)"
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            code:
              description: >-
                One of the following error codes:

                - missingCredentials: No credentials provided.

                - invalidCredentials: Provided credentials are invalid or
                expired
              $ref: "#/components/schemas/Error401Code"
          required:
            - code
    Error401Code:
      description: |-
        One of the following error codes:
        - missingCredentials: No credentials provided.
        - invalidCredentials: Provided credentials are invalid or expired
      type: string
      enum:
        - missingCredentials
        - invalidCredentials
    Error403:
      description: >-
        Forbidden. This code indicates that the server understood the request
        but refuses to authorize it.
        (https://tools.ietf.org/html/rfc7231#section-6.5.3)
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            code:
              description: |-
                This code indicates that the server understood
                the request but refuses to authorize it because
                of one of the following error codes:
                - accessDenied: Access denied
                - forbiddenRequester: Forbidden requester
                - tooManyUsers: Too many users
              $ref: "#/components/schemas/Error403Code"
          required:
            - code
    Error403Code:
      description: |-
        This code indicates that the server understood
        the request but refuses to authorize it because
        of one of the following error codes:
        - accessDenied: Access denied
        - forbiddenRequester: Forbidden requester
        - tooManyUsers: Too many users
      type: string
      enum:
        - accessDenied
        - forbiddenRequester
        - tooManyUsers
    Error404:
      description: >-
        Resource for the requested path not found.
        (https://tools.ietf.org/html/rfc7231#section-6.5.4)
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            code:
              description: >-
                The following error code:

                - notFound: A current representation for the target resource not
                found
              type: string
              enum:
                - notFound
          required:
            - code
    Error422:
      description: >-
        Unprocessable entity due to a business validation problem.
        (https://tools.ietf.org/html/rfc4918#section-11.2)
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            code:
              description: |
                One of the following error codes:
                  - missingProperty: The property that was expected is not present in the payload
                  - invalidValue: The property has an incorrect value
                  - invalidFormat: The property value does not comply with the expected value format
                  - referenceNotFound: The object referenced by the property cannot be identified in the target system
                  - unexpectedProperty: Additional, not expected property has been provided
                  - tooManyRecords: the number of records to be provided in the response exceeds the  threshold.
                  - otherIssue: Other problem was identified (detailed information provided in a reason)
              $ref: "#/components/schemas/Error422Code"
            propertyPath:
              description: >
                A pointer to a particular property of the payload that caused
                the validation issue. It is highly recommended that this
                property should be used.

                Defined using JavaScript Object Notation (JSON) Pointer
                (https://tools.ietf.org/html/rfc6901).
              type: string
          required:
            - code
    Error422Code:
      description: >
        One of the following error codes:

        - missingProperty: The property that was expected is not present in the
        payload

        - invalidValue: The property has an incorrect value

        - invalidFormat: The property value does not comply with the expected
        value format

        - referenceNotFound: The object referenced by the property cannot be
        identified in the target system

        - unexpectedProperty: Additional, not expected property has been
        provided

        - tooManyRecords: the number of records to be provided in the response
        exceeds the  threshold.

        - otherIssue: Other problem was identified (detailed information
        provided in a reason)
      type: string
      enum:
        - missingProperty
        - invalidValue
        - invalidFormat
        - referenceNotFound
        - unexpectedProperty
        - tooManyRecords
        - otherIssue
    Error500:
      description: >-
        Internal Server Error.
        (https://tools.ietf.org/html/rfc7231#section-6.6.1)
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            code:
              description: >-
                The following error code:

                - internalError: Internal server error - the server encountered
                an unexpected condition that prevented it from fulfilling the
                request.
              type: string
              enum:
                - internalError
          required:
            - code
    EventSubscription:
      description: |
        This resource is used to respond to notification subscriptions.
      type: object
      properties:
        callback:
          description: >-
            The value provided by in `EventSubscriptionInput` during
            notification registration
          type: string
        id:
          description: >-
            An identifier of this Event Subscription assigned when a resource is
            created.
          type: string
        query:
          description: >-
            The value provided by the `EventSubscriptionInput` during
            notification registration
          type: string
      required:
        - callback
        - id
    EventSubscriptionInput:
      description: This class is used to register for Notifications.
      type: object
      properties:
        callback:
          description: >-
            This callback value must be set to *host* property from Service
            Order Notification API (serviceOrderNotification.api.yaml). This
            property is appended with the base path and notification resource
            path specified in that API to construct an URL to which notification
            is sent. E.g. for "callback": "https://client.mef.com/listenerEndpoint",
            the service order state change event notification will be sent to:
            `https://client.mef.com/listenerEndpoint/mefApi/legato/serviceOrderingManagement/v6/listener/serviceOrderStateChangeEvent`
          type: string
        query:
          description: >-
            This attribute is used to define to which type of events to register
            to. Example: "query":"eventType = serviceOrderStateChangeEvent". To
            subscribe for more than one event type, put the values separated by
            comma:
            `eventType=serviceOrderStateChangeEvent,serviceOrderItemStateChangeEvent`.
            The possible values are enumerated by 'serviceOrderEventType' in
            serviceOrderNotification.api.yaml. An empty query is treated as
            specifying no filters - ending in subscription for all event types.
          type: string
      required:
        - callback
    FieldedAddressRepresentation:
      description: >-
        A type of Address that has a discrete field and value for each type of
        boundary or identifier down to the lowest level of detail. For example
        "street number" is one field, "street name" is another field, etc.
      type: object
      properties:
        streetNr:
          description: >-
            Number identifying a specific property on a public street. It may be
            combined with streetNrLast for ranged addresses.
          type: string
        streetNrSuffix:
          description: >-
            The first street number suffix (in a street number range) or the
            suffix for the street number if there is no range
          type: string
        streetNrLast:
          description:
            Last number in a range of street numbers allocated to an Address
          type: string
        streetNrLastSuffix:
          description: Last street number suffix for a ranged Address
          type: string
        streetPreDirection:
          description:
            The direction of the street that appears before the Street Name
          type: string
        streetName:
          description: Name of the street or other street type
          type: string
        streetType:
          description: >-
            The type of street (e.g., alley, avenue, boulevard, brae, crescent,
            drive, highway, lane, terrace, parade, place, tarn, way, wharf)
          type: string
        streetPostDirection:
          description: >-
            A modifier denoting a relative direction that appears after the
            Street Name.
          type: string
        poBox:
          description: >-
            Number identifying a specific location in a post office.
          type: string
        locality:
          description: >-
            An area of defined or undefined boundaries within a local authority
            or other legislatively defined area.
          type: string
        city:
          description: City in which the Address is located.
          type: string
        postcode:
          description: >-
            A descriptor for a postal delivery area used to speed and simplify
            the delivery of mail (also known as zip code)
          type: string
        postcodeExtension:
          description: >-
            The extension used on a postal code. Note: there are different use
            codes for this attribute depending upon the country.
          type: string
        stateOrProvince:
          description: The State or Province in which the Address is located.
          type: string
        countryCode:
          description: >-
            Country in which the Address is located, defined using two
            characters as defined in ISO 3166
          type: string
          minLength: 2
          maxLength: 2
        subUnit:
          description: >-
            The Sub Unit represented as a list. This is a list to allow complex
            sub-unit information such as SUITE 42 ROOM A
          type: array
          items:
            $ref: '#/components/schemas/SubUnit'
        buildingName:
          description: >
            The well-known name of a building that is located at this Address
            (e.g., where there is one Address for a campus).
          type: string
        privateStreetNumber:
          description: Street number on a private street within the Address.
          type: string
        privateStreetName:
          description: >-
            Private streets internal to a property (e.g., a university) may have
            internal names that are not recorded by the land title office.
          type: string
        language:
          description: >-
            The language in which the address is expressed. It MUST use the ISO 639:2023 two letter code
            639:2023
          type: string
          minLength: 2
          maxLength: 2
    FormattedAddressRepresentation:
      description:
        'A freeform text representation agreed to by the BUS and SOF. '
      type: object
      properties:
        formattedAddress:
          description: >-
            A formatted Address Representation that contains a non-fielded
            address.
          type: string
        language:
          description: >-
            The language in which the address is expressed. Based on ISO
            639:2023
          type: string
          minLength: 2
          maxLength: 2
      required:
        - formattedAddress
    GeographicAddressRef:
      description: >
        A reference to a Geographic Address resource available through Address
        Validation API.
      type: object
      properties:
        href:
          description: >
            Hyperlink to the referenced Address. Hyperlink MAY be used by the
            SOF in responses. Hyperlink MUST be ignored by the SOF in case
            it is provided by the BUS in a request.
          type: string
        id:
          description: >-
            Identifier of the referenced Geographic Address. This identifier is
            assigned during a successful address validation request (Geographic
            Address Management API)
          type: string
        '@type':
          description:
            Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
            - GeographicAddressRef
      required:
        - '@type'
        - id
    GeographicAddress_Query:
      description: >-
        A list of representations being a subset of Geographic Address entity.
        This is to be used when providing a list of representations to validate
        a Geographic Address
      type: object
      properties:
        fieldedAddressRepresentation:
          description: A list of Fielded Address representations
          type: array
          items:
            $ref: '#/components/schemas/FieldedAddressRepresentation'
        formattedAddressRepresentation:
          description: A list of Formatted Address representations
          type: array
          items:
            $ref: '#/components/schemas/FormattedAddressRepresentation'
        geographicPointRepresentation:
          description: A list of Geographic Point Address representations
          type: array
          items:
            $ref: '#/components/schemas/GeographicPointRepresentation'
        l

# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-legato-service-ordering-management-openapi.yml