TM Forum serviceSpecification API

openapi: 3.2.0
info:
  title: Service Catalog Management Service Specification API
  description: "## TMF API Reference: TMF633 - Service Catalog Management\n\n Version 4.0 \n\nThe Service Catalog API is one of Catalog Management API Family. Service Catalog API goal is to provide a catalog of services. \nService Catalog API performs the following operations on the resource :\n- Retrieve an entity or a collection of entities depending on filter criteria\n- Partial update of an entity (including updating rules)\n- Create an entity (including default values and creation rules)\n- Delete an entity (for administration purposes)\n- Manage notification of events. .\n\nCopyright © TM Forum 2020. All Rights Reserved. "
  version: 4.0.0
servers:
- url: https://serverRoot/tmf-api/serviceCatalogManagement/v4/
tags:
- name: serviceSpecification
paths:
  /serviceSpecification:
    get:
      operationId: listServiceSpecification
      summary: List or find ServiceSpecification objects
      description: This operation list or find ServiceSpecification entities
      tags:
      - serviceSpecification
      parameters:
      - name: fields
        description: Comma-separated properties to be provided in response
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceSpecification'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createServiceSpecification
      summary: Creates a ServiceSpecification
      description: This operation creates a ServiceSpecification entity.
      tags:
      - serviceSpecification
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceSpecification'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceSpecification_Create'
        description: The ServiceSpecification to be created
        required: true
  /serviceSpecification/{id}:
    get:
      operationId: retrieveServiceSpecification
      summary: Retrieves a ServiceSpecification by ID
      description: This operation retrieves a ServiceSpecification entity. Attribute selection is enabled for all first level attributes.
      tags:
      - serviceSpecification
      parameters:
      - name: id
        description: Identifier of the ServiceSpecification
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceSpecification'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchServiceSpecification
      summary: Updates partially a ServiceSpecification
      description: This operation updates partially a ServiceSpecification entity.
      tags:
      - serviceSpecification
      parameters:
      - name: id
        description: Identifier of the ServiceSpecification
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceSpecification'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceSpecification_Update'
        description: The ServiceSpecification to be updated
        required: true
    delete:
      operationId: deleteServiceSpecification
      summary: Deletes a ServiceSpecification
      description: This operation deletes a ServiceSpecification entity.
      tags:
      - serviceSpecification
      parameters:
      - name: id
        description: Identifier of the ServiceSpecification
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Quantity:
      type: object
      description: An amount in a given unit
      properties:
        amount:
          default: 1
          type: number
          format: float
          description: Numeric value in a given unit
        units:
          type: string
          description: Unit
    TargetEntitySchema:
      type: object
      description: The reference object to the schema and type of target entity which is described by a specification
      required:
      - '@schemaLocation'
      - '@type'
      properties:
        '@schemaLocation':
          type: string
          description: This field provides a link to the schema describing the target entity
        '@type':
          type: string
          description: Class type of the target entity
    Error:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      type: object
      required:
      - code
      - reason
      properties:
        code:
          type: string
          description: Application relevant detail, defined in the API or a common list.
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.
        status:
          type: string
          description: HTTP Error code extension
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
    CharacteristicValueSpecification:
      type: object
      description: specification of a value (number or text or an object) that can be assigned to a Characteristic.
      properties:
        isDefault:
          type: boolean
          description: If true, the Boolean Indicates if the value is the default value for a characteristic
        rangeInterval:
          type: string
          description: An indicator that specifies the inclusion or exclusion of the valueFrom and valueTo attributes. If applicable, possible values are "open", "closed", "closedBottom" and "closedTop".
        regex:
          type: string
          description: A regular expression constraint for given value
        unitOfMeasure:
          type: string
          description: A length, surface, volume, dry measure, liquid measure, money, weight, time, and the like. In general, a determinate quantity or magnitude of the kind designated, taken as a standard of comparison for others of the same kind, in assigning to them numerical values, as 1 foot, 1 yard, 1 mile, 1 square foot.
        valueFrom:
          type: integer
          description: The low range value that a characteristic can take on
        valueTo:
          type: integer
          description: The upper range value that a characteristic can take on
        valueType:
          type: string
          description: A kind of value that the characteristic value can take on, such as numeric, text and so forth
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period of time for which a value is applicable.
        value:
          $ref: '#/components/schemas/Any'
          description: A discrete value that the characteristic can take on, or the actual value of the characteristic
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
    FeatureSpecificationRelationship:
      type: object
      description: Relationship between feature specifications
      required:
      - name
      - relationshipType
      properties:
        featureId:
          type: string
          description: Unique identifier of the target feature specification.
        name:
          type: string
          description: This is the name of the target feature specification.
        parentSpecificationHref:
          type: string
          format: uri
          description: Hyperlink reference to the parent specification containing the target feature
        parentSpecificationId:
          type: string
          description: Unique identifier of the parent specification containing the target feature
        relationshipType:
          type: string
          description: This is the type of the feature specification relationship.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which this feature spoecification relationship is valid.
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format
    FeatureSpecificationCharacteristic:
      type: object
      description: Configuration feature characteristic specification.
      required:
      - name
      properties:
        id:
          type: string
          description: Unique ID for the characteristic
        configurable:
          type: boolean
          description: If true, the Boolean indicates that the target Characteristic is configurable
        description:
          type: string
          description: A narrative that explains the CharacteristicSpecification.
        extensible:
          type: boolean
          description: An indicator that specifies that the values for the characteristic can be extended by adding new values when instantiating a characteristic for a resource.
        isUnique:
          type: boolean
          description: An indicator that specifies if a value is unique for the specification. Possible values are; "unique while value is in effect" and "unique whether value is in effect or not"
        maxCardinality:
          type: integer
          description: The maximum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where five is the value for the maxCardinality.
        minCardinality:
          type: integer
          description: The minimum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where zero is the value for the minCardinality.
        name:
          type: string
          description: A word, term, or phrase by which this characteristic specification is known and distinguished from other characteristic specifications.
        regex:
          type: string
          description: A rule or principle represented in regular expression used to derive the value of a characteristic value.
        valueType:
          type: string
          description: A kind of value that the characteristic can take on, such as numeric, text and so forth
        featureSpecCharRelationship:
          type: array
          items:
            $ref: '#/components/schemas/FeatureSpecificationCharacteristicRelationship'
          description: An aggregation, migration, substitution, dependency or exclusivity relationship between/among feature characteristics.
        featureSpecCharacteristicValue:
          type: array
          items:
            $ref: '#/components/schemas/CharacteristicValueSpecification'
          description: Used to define a set of attributes, each of which can be assigned to a corresponding set of attributes in a FeatureCharacteristic object.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period of time for which a characteristic is applicable.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@valueSchemaLocation':
          type: string
          description: This (optional) field provides a link to the schema describing the value type.
    AttachmentRefOrValue:
      type: object
      description: An attachment by value or by reference. An attachment complements the description of an element, for example through a document, a video, a picture.
      properties:
        id:
          example: 4aafacbd-11ff-4dc8-b445-305f2215715f
          type: string
          description: Unique identifier for this particular attachment
        href:
          example: http://host/Attachment/4aafacbd-11ff-4dc8-b445-305f2215715f
          type: string
          format: uri
          description: URI for this Attachment
        attachmentType:
          example: video
          type: string
          description: Attachment type such as video, picture
        content:
          type: string
          format: base64
          description: The actual contents of the attachment object, if embedded, encoded as base64
        description:
          example: Photograph of the Product
          type: string
          description: A narrative text describing the content of the attachment
        mimeType:
          type: string
          description: Attachment mime type such as extension file for video, picture and document
        name:
          type: string
          description: The name of the attachment
        url:
          example: http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f
          type: string
          format: uri
          description: Uniform Resource Locator, is a web page address (a subset of URI)
        size:
          $ref: '#/components/schemas/Quantity'
          description: The size of the attachment.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period of time for which the attachment is valid
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    EntitySpecificationRelationship:
      type: object
      description: A migration, substitution, dependency or exclusivity relationship between/among entity specifications.
      required:
      - relationshipType
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        relationshipType:
          type: string
          description: Type of relationship such as migration, substitution, dependency, exclusivity
        role:
          type: string
          description: The association role for this entity specification
        associationSpec:
          $ref: '#/components/schemas/AssociationSpecificationRef'
          description: A specification for an association used by this relationship
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the entitySpecRelationship is valid
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    CharacteristicSpecification:
      type: object
      description: This class defines a characteristic specification.
      properties:
        id:
          type: string
          description: Unique ID for the characteristic
        configurable:
          type: boolean
          description: If true, the Boolean indicates that the target Characteristic is configurable
        description:
          type: string
          description: A narrative that explains the CharacteristicSpecification.
        extensible:
          type: boolean
          description: An indicator that specifies that the values for the characteristic can be extended by adding new values when instantiating a characteristic for a resource.
        isUnique:
          type: boolean
          description: An indicator that specifies if a value is unique for the specification. Possible values are; "unique while value is in effect" and "unique whether value is in effect or not"
        maxCardinality:
          type: integer
          description: The maximum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where five is the value for the maxCardinality.
        minCardinality:
          type: integer
          description: The minimum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where zero is the value for the minCardinality.
        name:
          type: string
          description: A word, term, or phrase by which this characteristic specification is known and distinguished from other characteristic specifications.
        regex:
          type: string
          description: A rule or principle represented in regular expression used to derive the value of a characteristic value.
        valueType:
          type: string
          description: A kind of value that the characteristic can take on, such as numeric, text and so forth
        charSpecRelationship:
          type: array
          items:
            $ref: '#/components/schemas/CharacteristicSpecificationRelationship'
          description: An aggregation, migration, substitution, dependency or exclusivity relationship between/among Specification Characteristics.
        characteristicValueSpecification:
          type: array
          items:
            $ref: '#/components/schemas/CharacteristicValueSpecification'
          description: A CharacteristicValueSpecification object is used to define a set of attributes, each of which can be assigned to a corresponding set of attributes in a CharacteristicSpecification object. The values of the attributes in the CharacteristicValueSpecification object describe the values of the attributes that a corresponding Characteristic object can take on.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period of time for which a characteristic is applicable.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@valueSchemaLocation':
          type: string
          description: This (optional) field provides a link to the schema describing the value type.
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: Role played by the related party
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    ServiceSpecification:
      type: object
      description: 'ServiceSpecification is a class that offers characteristics to describe a type of service.

        Functionally, it acts as a template by which Services may be instantiated. By sharing the same specification, these services would therefore share the same set of characteristics.'
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        description:
          type: string
          description: Description of the specification
        isBundle:
          type: boolean
          description: isBundle determines whether specification represents a single specification (false), or a bundle of specifications (true).
        lastUpdate:
          type: string
          format: date-time
          description: Date and time of the last update of the specification
        lifecycleStatus:
          type: string
          description: Used to indicate the current lifecycle status of this catalog item
        name:
          type: string
          description: Name given to the specification
        version:
          type: string
          description: specification version
        attachment:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRefOrValue'
          description: Attachments that may be of relevance to this specification, such as picture, document, media
        constraint:
          type: array
          items:
            $ref: '#/components/schemas/ConstraintRef'
          description: This is a list of constraint references applied to this specification
        entitySpecRelationship:
          type: array
          items:
            $ref: '#/components/schemas/EntitySpecificationRelationship'
          description: Relationship to another specification
        featureSpecification:
          type: array
          items:
            $ref: '#/components/schemas/FeatureSpecification'
          description: A list of Features for this specification.
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: Parties who manage or otherwise have an interest in this specification
        resourceSpecification:
          type: array
          items:
            $ref: '#/components/schemas/ResourceSpecificationRef'
          description: A list of resource specification references (ResourceSpecificationRef [*]). The ResourceSpecification is required for a service specification with type ResourceFacingServiceSpecification (RFSS).
        serviceLevelSpecification:
          type: array
          items:
            $ref: '#/components/schemas/ServiceLevelSpecificationRef'
          description: A list of service level specifications related to this service specification, and which will need to be satisifiable for corresponding service instances; e.g. Gold, Platinum
        serviceSpecRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceSpecRelationship'
          description: A list of service specifications related to this specification, e.g. migration, substitution, dependency or exclusivity relationship
        specCh

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-servicespecification-api-openapi.yml