openapi: 3.0.1
info:
title: Product Catalog Management agreement productOffering API
description: "Product Catalog API is one of Catalog Management API Family. Product Catalog API goal is to provide a catalog of products. \n### Operations\nProduct Catalog API performs the following operations on the resources :\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\n- Manage notification of events"
version: 5.0.0
servers:
- url: https://serverRoot/productCatalogManagement/v5/
tags:
- name: productOffering
description: Operations for ProductOffering Resource
paths:
/productOffering:
get:
tags:
- productOffering
summary: TM Forum List or Find ProductOffering Objects
description: List or find ProductOffering objects
operationId: listProductOffering
parameters:
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
$ref: '#/components/responses/200ProductOfferingArray'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
post:
tags:
- productOffering
summary: TM Forum Creates a ProductOffering
description: This operation creates a ProductOffering entity.
operationId: createProductOffering
parameters:
- $ref: '#/components/parameters/Fields'
requestBody:
$ref: '#/components/requestBodies/ProductOffering_FVO'
responses:
'201':
$ref: '#/components/responses/201ProductOffering'
'202':
description: Accepted
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
/productOffering/{id}:
get:
tags:
- productOffering
summary: TM Forum Retrieves a ProductOffering by ID
description: This operation retrieves a ProductOffering entity. Attribute selection enabled for all first level attributes.
operationId: retrieveProductOffering
parameters:
- $ref: '#/components/parameters/Id'
- $ref: '#/components/parameters/Fields'
responses:
'200':
$ref: '#/components/responses/200ProductOffering_Get'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
patch:
tags:
- productOffering
summary: TM Forum Updates Partially a ProductOffering
description: This operation updates partially a ProductOffering entity.
operationId: patchProductOffering
parameters:
- $ref: '#/components/parameters/Id'
- $ref: '#/components/parameters/Fields'
requestBody:
$ref: '#/components/requestBodies/ProductOffering_MVO'
responses:
'200':
$ref: '#/components/responses/200ProductOffering_Patch'
'202':
description: Accepted
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
delete:
tags:
- productOffering
summary: TM Forum Deletes a ProductOffering
description: This operation deletes a ProductOffering entity.
operationId: deleteProductOffering
parameters:
- $ref: '#/components/parameters/Id'
responses:
'202':
$ref: '#/components/responses/202'
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
components:
schemas:
ProductOfferingPriceRefOrValue:
type: object
description: The polymorphic attributes @type, @schemaLocation & @referredType are related to the ProductOfferingPrice entity and not the ProductOfferingPriceRefOrValue class itself
oneOf:
- $ref: '#/components/schemas/ProductOfferingPrice'
- $ref: '#/components/schemas/ProductOfferingPriceRef'
discriminator:
propertyName: '@type'
mapping:
ProductOfferingPrice: '#/components/schemas/ProductOfferingPrice'
ProductOfferingPriceRef: '#/components/schemas/ProductOfferingPriceRef'
AgreementRef:
type: object
description: Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.
allOf:
- $ref: '#/components/schemas/Extensible'
- $ref: '#/components/schemas/EntityRef'
discriminator:
propertyName: '@type'
mapping:
AgreementRef: '#/components/schemas/AgreementRef'
EntityRef_FVO:
allOf:
- $ref: '#/components/schemas/Extensible_FVO'
- $ref: '#/components/schemas/Addressable_FVO'
- type: object
description: Entity reference schema to be use for all entityRef class.
properties:
id:
type: string
description: The identifier of the referred entity.
href:
type: string
description: The URI of the referred entity.
name:
type: string
description: Name of the referred entity.
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
ProductOfferingPriceRefOrValue_FVO:
type: object
description: The polymorphic attributes @type, @schemaLocation & @referredType are related to the ProductOfferingPrice entity and not the ProductOfferingPriceRefOrValue class itself
oneOf:
- $ref: '#/components/schemas/ProductOfferingPrice_FVO'
- $ref: '#/components/schemas/ProductOfferingPriceRef_FVO'
discriminator:
propertyName: '@type'
mapping:
ProductOfferingPrice: '#/components/schemas/ProductOfferingPrice_FVO'
ProductOfferingPriceRef: '#/components/schemas/ProductOfferingPriceRef_FVO'
PlaceRef:
type: object
description: Place reference.
allOf:
- $ref: '#/components/schemas/Extensible'
- $ref: '#/components/schemas/EntityRef'
discriminator:
propertyName: '@type'
mapping:
PlaceRef: '#/components/schemas/PlaceRef'
ProductSpecificationCharacteristicValueUse_MVO:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: A use of the ProductSpecificationCharacteristicValue by a ProductOffering to which additional properties (attributes) apply or override the properties of similar properties contained in ProductSpecificationCharacteristicValue. It should be noted that characteristics which their value(s) addressed by this object must exist in corresponding product specification. The available characteristic values for a ProductSpecificationCharacteristic in a Product specification can be modified at the ProductOffering level. For example, a characteristic 'Color' might have values White, Blue, Green, and Red. But, the list of values can be restricted to e.g. White and Blue in an associated product offering. It should be noted that the list of values in 'ProductSpecificationCharacteristicValueUse' is a strict subset of the list of values as defined in the corresponding product specification characteristics.
properties:
name:
type: string
description: Name of the associated productSpecificationCharacteristic
id:
type: string
description: Unique ID for the characteristic
description:
type: string
description: A narrative that explains in detail what the productSpecificationCharacteristic is
valueType:
type: string
description: A kind of value that the characteristic can take on, such as numeric, text and so forth
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.
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.
validFor:
$ref: '#/components/schemas/TimePeriod'
productSpecCharacteristicValue:
type: array
items:
$ref: '#/components/schemas/CharacteristicValueSpecification_MVO'
description: A number or text that can be assigned to a ProductSpecificationCharacteristic.
productSpecification:
$ref: '#/components/schemas/ProductSpecificationRef_MVO'
discriminator:
propertyName: '@type'
mapping:
ProductSpecificationCharacteristicValueUse: '#/components/schemas/ProductSpecificationCharacteristicValueUse_MVO'
ProductOfferingRef_MVO:
allOf:
- $ref: '#/components/schemas/EntityRef'
- type: object
description: ProductOffering reference. A product offering represents entities that are orderable from the provider of the catalog, this resource includes pricing information.
properties:
version:
type: string
description: Version of the product offering
discriminator:
propertyName: '@type'
mapping:
ProductOfferingRef: '#/components/schemas/ProductOfferingRef_MVO'
BundledProductOffering: '#/components/schemas/BundledProductOffering_MVO'
CharacteristicSpecificationRelationship_MVO:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: An aggregation, migration, substitution, dependency or exclusivity relationship between/among Characteristic specifications. The specification characteristic is embedded within the specification whose ID and href are in this entity, and identified by its ID.
properties:
relationshipType:
type: string
description: Type of relationship such as aggregation, migration, substitution, dependency, exclusivity
name:
type: string
description: Name of the target characteristic within the specification
characteristicSpecificationId:
type: string
description: Unique identifier of the characteristic within the specification
parentSpecificationHref:
type: string
format: uri
description: Hyperlink reference to the parent specification containing the target characteristic
validFor:
$ref: '#/components/schemas/TimePeriod'
parentSpecificationId:
type: string
description: Unique identifier of the parent specification containing the target characteristic
required:
- parentSpecificationId
- name
- relationshipType
discriminator:
propertyName: '@type'
mapping:
CharacteristicSpecificationRelationship: '#/components/schemas/CharacteristicSpecificationRelationship_MVO'
Attachment:
allOf:
- $ref: '#/components/schemas/Entity'
- type: object
description: Complements the description of an element (for instance a product) through video, pictures...
properties:
name:
type: string
description: The name of the attachment
description:
type: string
description: A narrative text describing the content of the attachment
example: Photograph of the Product
url:
type: string
description: Uniform Resource Locator, is a web page address (a subset of URI)
example: http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f
content:
type: string
format: base64
description: The actual contents of the attachment object, if embedded, encoded as base64
size:
$ref: '#/components/schemas/Quantity'
validFor:
$ref: '#/components/schemas/TimePeriod'
attachmentType:
type: string
description: a business characterization of the purpose of the attachment, for example logo, instructionManual, contractCopy
mimeType:
type: string
description: a technical characterization of the attachment content format using IETF Mime Types
discriminator:
propertyName: '@type'
mapping:
Attachment: '#/components/schemas/Attachment'
ProductOfferingRelationship:
allOf:
- $ref: '#/components/schemas/EntityRef'
- type: object
description: A relationship between two product Offerings.
properties:
role:
type: string
description: The association role for the source product offering
name:
type: string
description: Name of the referred product offering type.
validFor:
$ref: '#/components/schemas/TimePeriod'
relationshipType:
type: string
description: Type of relationship between product offerings such as requires, exchangableTo, optionalFor
version:
type: string
description: Version of the referred product offering.
discriminator:
propertyName: '@type'
mapping:
ProductOfferingRelationship: '#/components/schemas/ProductOfferingRelationship'
BundledGroupProductOffering_FVO:
allOf:
- $ref: '#/components/schemas/Extensible_FVO'
- type: object
description: A group of product offerings that can be chosen for instantiation of children of the parent product offering, for example a list of channels for selection under a TV offering. Sometimes known as Selection Group. The group can also hierarchically contain other groups
properties:
id:
type: string
description: Locally unique identifier of the group, useful in case the parent product offering or group includes multiple groups.
example: '1'
name:
type: string
description: The name of the group of child offerings. Required to distinguish several choice groups.
example: TV Channels
bundledProductOffering:
type: array
items:
$ref: '#/components/schemas/BundledProductOffering_FVO'
description: Child offerings, from which instances can be created as direct or hierarchically indirect children of the parent offering.
bundledGroupProductOffering:
type: array
items:
$ref: '#/components/schemas/BundledGroupProductOffering_FVO'
description: Child groups of product offerings, to enable hierarchical sub-grouping.
bundledGroupProductOfferingOption:
$ref: '#/components/schemas/BundledGroupProductOfferingOption_FVO'
required:
- name
discriminator:
propertyName: '@type'
mapping:
BundledGroupProductOffering: '#/components/schemas/BundledGroupProductOffering_FVO'
ChannelRef_FVO:
type: object
description: The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..
allOf:
- $ref: '#/components/schemas/EntityRef_FVO'
discriminator:
propertyName: '@type'
mapping:
ChannelRef: '#/components/schemas/ChannelRef_FVO'
BundledProductOfferingPriceRelationship:
allOf:
- $ref: '#/components/schemas/EntityRef'
- type: object
description: This represents a bundling pricing relationship, allowing a price to be composed of multiple other prices (e.g. a recurring charge and a onetime charge).
properties:
version:
type: string
description: Version of the referred product offering price.
discriminator:
propertyName: '@type'
mapping:
BundledProductOfferingPriceRelationship: '#/components/schemas/BundledProductOfferingPriceRelationship'
BundledProductOfferingOption_MVO:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: A set of numbers that specifies the lower and upper limits for a ProductOffering that can be procured as part of the related BundledProductOffering. Values can range from 0 to unbounded
properties:
numberRelOfferDefault:
type: integer
description: Default number of produc offereings that should be procured as part of the related BundledProductOffering
numberRelOfferLowerLimit:
type: integer
description: lower limit for a product offering that can be procured as part of the related BundledProductOffering
numberRelOfferUpperLimit:
type: integer
description: upper limit for a product offering that can be procured as part of the related BundledProductOffering
discriminator:
propertyName: '@type'
mapping:
BundledProductOfferingOption: '#/components/schemas/BundledProductOfferingOption_MVO'
BundledProductOfferingPriceRelationship_FVO:
allOf:
- $ref: '#/components/schemas/EntityRef_FVO'
- type: object
description: This represents a bundling pricing relationship, allowing a price to be composed of multiple other prices (e.g. a recurring charge and a onetime charge).
properties:
version:
type: string
description: Version of the referred product offering price.
required:
- id
discriminator:
propertyName: '@type'
mapping:
BundledProductOfferingPriceRelationship: '#/components/schemas/BundledProductOfferingPriceRelationship_FVO'
BundledGroupProductOfferingOption:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: Defines for a BundledProductOfferingGroup (i.e. a group of multiple child offerings of a parent product offering), how many instances from the child offerings can be chosen in total. For example facilitate the choice of between 2 and 7 channel packs from a list, and cause certain items to be selected by default
properties:
numberRelOfferLowerLimit:
type: integer
description: The minimum total number of instances of the child offerings directly of hierarchically in the group that should be instantiated
example: 2
numberRelOfferUpperLimit:
type: integer
description: The maximum total number of instances of the child offerings directly of hierarchically in the group that should be instantiated
example: 7
discriminator:
propertyName: '@type'
mapping:
BundledGroupProductOfferingOption: '#/components/schemas/BundledGroupProductOfferingOption'
AllowedProductAction_FVO:
allOf:
- $ref: '#/components/schemas/Extensible_FVO'
- type: object
description: Defines an action that can be taken on a product in the inventory as part of a product order. It is expected that this entity will be attached to product catalog items such as specifications and offerings
properties:
validFor:
$ref: '#/components/schemas/TimePeriod'
channel:
type: array
items:
$ref: '#/components/schemas/ChannelRef_FVO'
description: A list of sales channels in which this action is allowed; for instance Remove might be allowed only in an assisted channel not in a self-service channel
example:
id: '4406'
href: https://mycsp.com:8080/tmf-api/salesChannelManagement/v4/channel/4406
name: Online Channel
'@referredType': SalesChannel
'@type': ChannelRef
'@baseType': ''
'@schemaLocation': https://mycsp.com:8080/tmf-api/schemas/Common/ChannelRef.schema.json
action:
type: string
description: The name of the action
example: add
required:
- action
discriminator:
propertyName: '@type'
mapping:
AllowedProductAction: '#/components/schemas/AllowedProductAction_FVO'
ProductOffering_FVO:
allOf:
- $ref: '#/components/schemas/Entity_FVO'
- type: object
description: Represents entities that are orderable from the provider of the catalog, this resource includes pricing information.
properties:
description:
type: string
description: Description of the productOffering
isBundle:
type: boolean
description: isBundle determines whether a productOffering represents a single productOffering (false), or a bundle of productOfferings (true).
isSellable:
type: boolean
description: A flag indicating if this product offer can be sold stand-alone for sale or not. If this flag is false it indicates that the offer can only be sold within a bundle.
statusReason:
type: string
description: A string providing a complementary information on the value of the lifecycle status attribute.
validFor:
$ref: '#/components/schemas/TimePeriod'
version:
type: string
description: ProductOffering version
place:
type: array
items:
$ref: '#/components/schemas/PlaceRef_FVO'
description: Place defines the places where the products are sold or delivered.
serviceLevelAgreement:
$ref: '#/components/schemas/SLARef_FVO'
channel:
type: array
items:
$ref: '#/components/schemas/ChannelRef_FVO'
description: The channel defines the channel for selling product offerings.
serviceCandidate:
$ref: '#/components/schemas/ServiceCandidateRef_FVO'
category:
type: array
items:
$ref: '#/components/schemas/CategoryRef_FVO'
description: The category resource is used to group product offerings, service and resource candidates in logical containers. Categories can contain other categories and/or product offerings, resource or service candidates.
resourceCandidate:
$ref: '#/components/schemas/ResourceCandidateRef_FVO'
productOfferingTerm:
type: array
items:
$ref: '#/components/schemas/ProductOfferingTerm_FVO'
description: A condition under which a ProductOffering is made available to Customers. For instance, a productOffering can be offered with multiple commitment periods.
productOfferingPrice:
type: array
items:
$ref: '#/components/schemas/ProductOfferingPriceRefOrValue_FVO'
description: An amount, usually of money, that is asked for or allowed when a ProductOffering is bought, rented, or leased. The price is valid for a defined period of time and may not represent the actual price paid by a customer.
agreement:
type: array
items:
$ref: '#/components/schemas/AgreementRef_FVO'
description: An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.
bundledProductOffering:
type: array
items:
$ref: '#/components/schemas/BundledProductOffering_FVO'
description: A type of ProductOffering that belongs to a grouping of ProductOfferings made available to the market. It inherits of all attributes of ProductOffering.
bundledGroupProductOffering:
type: array
items:
$ref: '#/components/schemas/BundledGroupProductOffering_FVO'
description: A group of ProductOfferings that can be selected for instantiation, e.g. between 2 and 7 from a list of 15 channel packs.
attachment:
type: array
items:
$ref: '#/components/schemas/AttachmentRefOrValue_FVO'
description: Complements the description of an element (for instance a product) through video, pictures...
marketSegment:
type: array
items:
$ref: '#/components/schemas/MarketSegmentRef_FVO'
description: provides references to the corresponding market segment as target of product offerings. A market segment is grouping of Parties, GeographicAreas, SalesChannels, and so forth.
productOfferingRelationship:
type: array
items:
$ref: '#/components/schemas/ProductOfferingRelationship_FVO'
description: A relationship between this product offering and other product offerings.
productOfferingCharacteristic:
type: array
items:
$ref: '#/components/schemas/CharacteristicSpecification_FVO'
description: A characteristic quality or distinctive feature of a ProductOffering. The characteristic can take on a discrete value fixed at design (catalog authoring) time, such as Mobile Plan Rank, and is not generally modifiable at inventory level.
prodSpecCharValueUse:
type: array
items:
$ref: '#/components/schemas/ProductSpecificationCharacteristicValueUse_FVO'
description: A use of the ProductSpecificationCharacteristicValue by a ProductOffering to which additional properties (attributes) apply or override the properties of similar properties contained in ProductSpecificationCharacteristicValue. It should be noted that characteristics which their value(s) addressed by this object must exist in corresponding product specification. The available characteristic values for a ProductSpecificationCharacteristic in a Product specification can be modified at the ProductOffering level. For example, a characteristic 'Color' might have values White, Blue, Green, and Red. But, the list of values can be restricted to e.g. White and Blue in an associated product offering. It should be noted that the list of values in 'ProductSpecificationCharacteristicValueUse' is a strict subset of the list of values as defined in the corresponding product specification characteristics.
policy:
type: array
items:
$ref: '#/components/schemas/PolicyRef_FVO'
description: The Policy resource represents a policy/rule applied to ProductOffering.
allowedAction:
type: array
items:
$ref: '#/components/schemas/AllowedProductAction_FVO'
description: List of actions that can be executed (in context of a product order) on products instantiated from this offering
lastUpdate:
type: string
format: date-time
description: Date and time of the last update
lifecycleStatus:
type: string
description: Used to indicate the current lifecycle status
name:
type: string
description: Name of the productOffering
productSpecification:
$ref: '#/components/schemas/ProductSpecificationRef_FVO'
externalIdentifier:
type: array
description: List of external identifieers for the offering, e.g. identifier in source catalog
items:
$ref: '#/components/schemas/ExternalIdentifier_FVO'
required:
- lastUpdate
- lifecycleStatus
- name
- '@type'
discriminator:
propertyName: '@type'
mapping:
ProductOffering: '#/components/schemas/ProductOffering_FVO'
ProductOfferingPriceRefOrValue_MVO:
type: object
description: The polymorphic attributes @type, @schemaLocation & @referredType are related to the ProductOfferingPrice entity and not the ProductOfferingPriceRefOrValue class itself
oneOf:
- $ref: '#/components/schemas/ProductOfferingPrice_MVO'
- $ref: '#/components/schemas/ProductOfferingPriceRef_MVO'
discriminator:
propertyName: '@type'
mapping:
ProductOfferingPrice: '#/components/schemas/ProductOfferingPrice_MVO'
ProductOfferingPriceRef: '#/components/schemas/ProductOfferingPriceRef_MVO'
BundledGroupProductOffering:
allOf:
- $ref: '#/components/schemas/Extensible'
- type: object
description: A group of product offerings that can be chosen for instantiation of children of the parent product offering, for example a list of channels for selection under a TV offering. Sometimes known as Selection Group. The group can also hierarchically contain other groups
properties:
id:
type: string
description: Locally unique identifier of the group, useful in case the parent product offering or group includes multiple groups.
example: '1'
name:
type: string
description: The name of the group of child offerings. Required to distinguish several choice groups.
example: TV Channels
bundledProductOffering:
type: array
items:
$ref: '#/components/schemas/BundledProductOffering'
description: Child offerings, from which instances can be created as direct or hierarchically indirect children of the parent offering.
bundledGroupProductOffering:
type: array
items:
$ref: '#/components/schemas/BundledGroupProductOffering'
description: Child groups of product offerings
# --- truncated at 32 KB (211 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-productoffering-api-openapi.yml