MEF Product Specification API

openapi: 3.2.0
info:
  title: Mef Product Specification API
  version: 4.0.1
  description: 'Operations tagged productSpecification across 2 of this provider''s published API definitions: mef-lso-cantata-product-catalog-openapi.yml, mef-lso-sonata-product-catalog-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://{serverBase}/mefApi/cantata/productCatalog/v4/
  variables:
    serverBase:
      description: The base of Buyer's URL.
      default: mplify.net
- url: http://{serverBase}/mefApi/sonata/productCatalog/v4/
  variables:
    serverBase:
      description: The base of Buyer's URL.
      default: mplify.net
tags:
- name: productSpecification
paths:
  /productSpecification:
    get:
      tags:
      - productSpecification
      summary: List or find ProductSpecification objects
      description: This operation list or find ProductSpecification entities
      operationId: listProductSpecification
      parameters:
      - name: name
        in: query
        description: The name of the Product Specification (may not be unique)
        required: false
        schema:
          type: string
      - name: lifecycleStatus
        in: query
        description: Lifecycle Status of the Product Specification
        required: false
        schema:
          type: string
          enum:
          - obsolete
          - published
      - name: lastUpdate.gt
        in: query
        description: The date and time the Product Specification was created or most recently updated, greater than
        required: false
        schema:
          type: string
          format: date-time
      - name: lastUpdate.lt
        in: query
        description: The date and time the Product Specification was created or most recently updated, less than
        required: false
        schema:
          type: string
          format: date-time
      - name: agreement
        in: query
        description: The name of the Seller's standard offer arrangement (such as a framework agreement). The name is unique within the Seller domain. This should be the name of the Seller's standard offer arrangement or framework agreement for the Product Specification.
        required: false
        schema:
          type: string
      - name: buyerId
        in: query
        description: The unique identifier of the organization that is acting as 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 the responding entity represents more than one Seller.
        required: false
        schema:
          type: string
      - name: offset
        in: query
        description: Requested index for the start of an 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 the 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/ProductSpecification_Find'
        '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':
          content:
            application/json;charset=utf-8:
              schema:
                items:
                  $ref: '#/components/schemas/Error422'
                type: array
          description: Unprocessable entity due to the business validation problems
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
    servers:
    - url: http://{serverBase}/mefApi/cantata/productCatalog/v4/
      variables:
        serverBase:
          description: The base of Buyer's URL.
          default: mplify.net
  /productSpecification/{id}:
    get:
      tags:
      - productSpecification
      summary: Retrieves a ProductSpecification by ID
      description: This operation retrieves a ProductSpecification entity. Attribute selection is enabled for all first level attributes.
      operationId: retrieveProductSpecification
      parameters:
      - name: id
        in: path
        description: Identifier of the ProductSpecification
        required: true
        schema:
          type: string
      - name: buyerId
        in: query
        description: The unique identifier of the organization that is acting as 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/ProductSpecification'
        '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'
    servers:
    - url: http://{serverBase}/mefApi/cantata/productCatalog/v4/
      variables:
        serverBase:
          description: The base of Buyer's URL.
          default: mplify.net
components:
  schemas:
    PlaceRelationshipConstraint:
      description: Allows definition and constraining of PlaceRelationship that can be specified for the ordered Product.
      type: object
      properties:
        relationshipRole:
          description: Specifies the nature of the relationship between the Product Offering and Place. This must be one of the roles as defined in the related Product Specification. For example, `INSTALL_LOCATION`.
          type: string
        isModifiable:
          description: Specifies if the Place Relationship can be modified on an active Product.
          type: boolean
        minCardinality:
          description: The minimum required number of PlaceRelationships of given relationshipRole that must configured for ordered Product. For example, as specified in the 'Relationship Between Entities' Section of MEF 106. `0` means the relation is optional.
          type: integer
          minimum: 0
        maxCardinality:
          description: The maximum required number of PlaceRelationships of given relationshipRole that must configured for ordered Product. For example, as specified in the 'Relationship Between Entities' Section of MEF 106. `-1` stands for infinity i.e. any number of instances of the given type could be related to the considered instance.
          type: integer
          minimum: -1
      required:
      - isModifiable
      - maxCardinality
      - minCardinality
      - relationshipRole
    ProductRelationshipConstraint:
      description: Allows definition and constraining of Product Relationship that can be specified for the ordered Product.
      type: object
      properties:
        productSpecification:
          description: The identifier of the associated Product Specification to define the allowable target Product types
          type: string
        relationshipType:
          description: Specifies the nature of productRelationship between Products. This must be one of the relationshipTypes as defined by the main product specification.
          type: string
        isModifiable:
          description: Specifies if the Product Relationship can be modified on an active Product.
          type: boolean
        minCardinality:
          description: The minimum required number of ProductRelationships (of given relationshipType and target productSpecification) that must configured for ordered Product. For example, as specified in the 'Relationship Between Entities' Section of MEF 106. `0` means the relation is optional.
          type: integer
          minimum: 0
        maxCardinality:
          description: The maximum required number of ProductRelationships (of given relationshipType and target productSpecification) that must configured for ordered Product. `-1` stands for infinity i.e. any number of instances of the given type could be related to the considered instance.
          type: integer
          minimum: -1
      required:
      - productSpecification
      - relationshipType
      - isModifiable
      - minCardinality
      - maxCardinality
    Note:
      description: Extra information about a given entity. Only useful in processes involving human interaction. Not applicable for the automated process.
      type: object
      properties:
        author:
          description: Author of the note
          type: string
        date:
          description: Date the Note was created
          type: string
          format: date-time
        id:
          description: Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation)
          type: string
        source:
          description: Indicates if the note is from Buyer or Seller
          $ref: '#/components/schemas/MEFBuyerSellerType'
        text:
          description: Text of the note
          type: string
      required:
      - author
      - date
      - id
      - source
      - text
    ProductSpecificationLifecycleStatusType:
      description: '| Name         | Mplify 127.1 Name | Description                                                                                                                                                                                                                                                                                                                                                                                                  |

        | ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

        | obsolete     | OBSOLETE          | The Product Specification is only available in the Product Catalog for historical documentation reasons. There are no active Products on the Seller''s Network based on the Product Specification. A Product Specification that is no longer available transitions to `obsolete` and may be removed at the Seller''s discretion from the Product Catalog. This is a final state. |

        | published    | PUBLISHED         | A Product Specification has been defined in the Product Catalog. Product Offerings based on the Product Specification may be available for ordering.                                                                                                                                                                                                                                                         |

        '
      type: string
      enum:
      - obsolete
      - published
    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
    ProductSpecification_Common:
      description: Is the basis for all Production Specification representations.
      type: object
      properties:
        id:
          description: Unique identifier for the Product Specification. For Mplify standardized products, this should be the Mplify assigned URN.
          type: string
        href:
          description: Reference of the Product Specification
          type: string
          format: uri
        name:
          description: Name of the Product Specification
          type: string
        lifecycleStatus:
          description: The current lifecycle status of the Product Specification.
          $ref: '#/components/schemas/ProductSpecificationLifecycleStatusType'
        lastUpdate:
          description: The date and time of an attribute within this Product Specification was created or most recently updated.
          type: string
          format: date-time
        agreement:
          description: The name of the Seller's standard offer arrangement (such as a framework agreement). The name is unique within the Seller domain. This should be the name of the Seller's standard offer arrangement or framework agreement for the Product Specification.
          type: string
    DataSizeUnit:
      description: The unit of measure in the data size.
      type: string
      enum:
      - BYTES
      - KBYTES
      - MBYTES
      - GBYTES
      - TBYTES
      - PBYTES
      - EBYTES
      - ZBYTES
      - YBYTES
    SchemaRefOrValue:
      description: Reference to the JSON schema location or the exact value of the JSON schema. **Note:** One of the properties must be provided i.e. schemaLocation or schema.
      type: object
      properties:
        schema:
          description: Raw JSON schema value.
          type: string
        schemaLocation:
          description: This field provides a link to the schema describing the target product
          type: string
          format: uri
    Error401Code:
      description: 'One of the following error codes:

        - missingCredentials: No credentials provided.

        - invalidCredentials: Provided credentials are invalid or expired'
      type: string
      enum:
      - missingCredentials
      - invalidCredentials
    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
    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
    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
    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
    MEFByteSize:
      description: A size represented by value and Byte units
      type: object
      properties:
        amount:
          description: Numeric value in a given unit
          type: number
          format: float
        units:
          description: Byte Unit
          $ref: '#/components/schemas/DataSizeUnit'
      required:
      - amount
      - units
    MEFBuyerSellerType:
      description: An enumeration with buyer and seller values.
      type: string
      enum:
      - buyer
      - seller
    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
    ProductSpecification:
      allOf:
      - $ref: '#/components/schemas/ProductSpecification_Common'
      - description: Is a detailed description of a tangible or intangible object made available externally in the form of a ProductOffering to customers or other parties playing a party role.
        properties:
          description:
            description: Description of the Product Specification.
            type: string
          attachment:
            description: 'Complements the Product Offering description with presentation, video, pictures, etc. Note: The Seller should include all documents describing the Standard Framework Agreement as an Attachment.'
            type: array
            items:
              $ref: '#/components/schemas/AttachmentValue'
          productRelationship:
            description: Specifies the relationships with their names between Products described by related Product Specifications. As an example, an Access E-Line OVC references an Operator UNI and an ENNI Product Specification.
            type: array
            items:
              $ref: '#/components/schemas/ProductRelationshipConstraint'
          placeRelationship:
            description: Specifies the relationships with their names between Product described by this Product Specifications and Place(s).
            type: array
            items:
              $ref: '#/components/schemas/PlaceRelationshipConstraint'
          milestone:
            description: Specifies the different milestones during the fulfillment process
            type: array
            items:
              $ref: '#/components/schemas/ProductMilestoneDefinition'
          note:
            description: 'A set of comments for additional information.

              '
            type: array
            items:
              $ref: '#/components/schemas/Note'
          sourceSchema:
            description: A reference to or value of the schemaProduct Schema as included in the Product Specification.
            $ref: '#/components/schemas/SchemaRefOrValue'
        required:
        - id
        - lastUpdate
        - lifecycleStatus
        - name
        - sourceSchema
        - description
    ProductMilestoneDefinition:
      description: Allows specifying the different stages of the Product provisioning process.
      type: object
      properties:
        name:
          description: The unique identifier of the milestone (as specified e.g. in the corresponding MEF Product Specification).
          type: string
        description:
          description: The explanation of what the milestone represents and when it occurs.
          type: string
      required:
      - description
      - name
    ProductSpecification_Find:
      allOf:
      - $ref: '#/components/schemas/ProductSpecification_Common'
      - description: Is a lightweight version of the Product Specification object used in Get List use case.
        required:
        - id
        - lastUpdate
        - lifecycleStatus
        - name
    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:
        reason:
          description: Text that explains the reason for the error. This can be shown to a client user.
          type: string
          maxLength: 255
        message:
          description: Text that provides mode details and corrective actions related to the error. This can be shown to a client user.
          type: string
        referenceError:
          description: URL pointing to documentation describing the error
          type: string
          format: uri
      required:
      - reason
    Error422:
      allOf:
      - $ref: '#/components/schemas/Error'
      - properties:
          code:
            $ref: '#/components/schemas/Error422Code'
            description: "One of the following error codes:\n  - missingProperty: The property the Seller has expected is not present in the payload\n  - invalidValue: The property has an incorrect value\n  - invalidFormat: The property value does not comply with the expected value format\n  - referenceNotFound: The object referenced by the property cannot be identified in the Seller system\n  - unexpectedProperty: Additional property, not expected by the Seller has been provided\n  - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n  - otherIssue: Other problem was identified (detailed information provided in a reason)\n"
          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
        type: object
      description: Unprocessable entity due to a business validation problem. (https://tools.ietf.org/html/rfc4918#section-11.2)
    Error422Code:
      description: "One of the following error codes:\n  - missingProperty: The property the Seller has expected is not present in the payload\n  - invalidValue: The property has an incorrect value\n  - invalidFormat: The property value does not comply with the expected value format\n  - referenceNotFound: The object referenced by the property cannot be identified in the Seller system\n  - unexpectedProperty: Additional property, not expected by the Seller has been provided\n  - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold.\n  - otherIssue: Other problem was identified (detailed information provided in a reason)\n"
      enum:
      - missingProperty
      - invalidValue
      - invalidFormat
      - referenceNotFound
      - unexpectedProperty
      - tooManyRecords
      - otherIssue
      type: string
    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
    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
x-refined-from:
- mef-lso-cantata-product-catalog-openapi.yml
- mef-lso-sonata-product-catalog-openapi.yml