Service Inventory Management — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Allegro SDK, Kylie release. LSO Allegro is the Interface Reference Point between a Customer and a Service Provider, covering the operational/service layer. 4 path(s), 5 operation(s). Apache-2.0 licensed and openly downloadable from public GitHub.
openapi: 3.0.3
info:
title: Service Inventory Management
description: |-
**This file forms part of Mplify 135.1**
Supported use cases:
- Retrieve Service List
- Retrieve Service by Identifier
Copyright 2025 Mplify Alliance and its contributors.
This file includes content based on the TM Forum Service Inventory Management API (TMF638
v4.0.1) available at https://github.com/tmforum-apis/TMF638_ServiceInventory,
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: 2.0.2
servers:
- url: 'https://{serverBase}/mefApi/allegro/serviceInventory/v2/'
variables:
serverBase:
description: The base of SOF's URL.
default: mplify.net
tags:
- name: Service
description: Mechanisms for BUS to query and retrieve *ServiceInstances*.
- name: Events subscription
description: Endpoints to register and terminate an Event Listener
paths:
/service:
get:
tags:
- Service
summary: Lists services
description: This operation lists Service entities.
operationId: serviceFind
parameters:
- name: state
in: query
description: The state of the service
required: false
schema:
$ref: '#/components/schemas/ServiceStateType'
- name: serviceDate.lt
in: query
description: >-
Less than the date when the service was created (whatever its
status)
required: false
schema:
type: string
format: date-time
- name: serviceDate.gt
in: query
description: >-
Greater than the date when the service was created (whatever its
status)
required: false
schema:
type: string
format: date-time
- name: startDate.lt
in: query
description: Less than the date when the service starts
required: false
schema:
type: string
format: date-time
- name: startDate.gt
in: query
description: Greater than the date when the service starts
required: false
schema:
type: string
format: date-time
- name: endDate.lt
in: query
description: Less than the date when the service ends
required: false
schema:
type: string
format: date-time
- name: endDate.gt
in: query
description: Greater than the date when the service ends
required: false
schema:
type: string
format: date-time
- name: serviceOrder.id
in: query
description: >-
A reference to a service order related to this service. Must be
used together with serviceOrderItem.id
required: false
schema:
type: string
- name: serviceOrderItem.id
in: query
description: >-
A reference to a service order item related to this service. Must
be used together with serviceOrder.id
required: false
schema:
type: string
- name: externalId
in: query
description: An externalId provided in the service order
required: false
schema:
type: string
- name: geographicSite.id
in: query
description:
A GeographicSite identifier which is associated to this service
required: false
schema:
type: string
- name: geographicAddress.id
in: query
description:
A GeographicAddress identifier which is associated to this service
required: false
schema:
type: string
- name: serviceType
in: query
description: Business type of the service
required: false
schema:
type: string
- name: '@type'
in: query
description:
The `@type` of `MefServiceConfiguration`. This is used to filter
the services by the precise `urn` of the Product Schema they have.
required: false
schema:
type: string
- name: startMode
in: query
description: |-
This attribute is an enumerated integer that indicates how the
Service is started, such as: 0: Unknown; 1: Automatically by
the managed environment; 2: Automatically by the owning device;
3: Manually by the Provider of the Service; 4: Manually by a
Customer of the Provider; 5: Any of the above
required: false
schema:
type: string
enum:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
- name: offset
in: query
description: >-
Requested index for start of item to be provided in response
requested by 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/Service'
'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'
deprecated: false
'/service/{id}':
get:
tags:
- Service
summary: Retrieve a service
description: This operation retrieves a service entity.
operationId: serviceGet
parameters:
- name: id
in: path
description: Identifier of the Service instance
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/Service'
'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'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'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 Hub by ID
description: This operation retrieves a hub entity.
operationId: retrieveHub
parameters:
- name: id
in: path
description: Identifier of the Hub
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 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'
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
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 the BUS in `EventSubscriptionInput` during
notification registration
type: string
id:
description: >-
An identifier of this Event Subscription assigned by the SOF when a
resource is created.
type: string
query:
description: >-
The value provided by the BUS in `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 BUS Service
Inventory Notification API (serviceInventoryNotification.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 state change
event notification will be sent to:
`https://client.mef.com/listenerEndpoint/mefApi/allegro/serviceInventoryNotification/v2/listener/serviceStateChangeEvent`
type: string
query:
description: >-
This attribute is used to define to which type of events to
register to. Example: "query":"eventType =
serviceStateChangeEvent". To subscribe for more than one event
type, put the values separated by comma:
`eventType=serviceCreateEvent,serviceStateChangeEvent`. The
possible values are enumerated by 'ServiceEventType' in
serviceInventoryNotification.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'
labelRepresentation:
description: A list of Label Address representations
type: array
items:
$ref: '#/components/schemas/LabelRepresentation'
'@type':
description:
Used to unambiguously designate the class type when using `oneOf`
ty
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-allegro-service-inventory-management-openapi.yml