Open APIs

 View Only
  • 1.  TMF620 - ProductOfferingRelationship exists in Swagger file but not in the datamodels

    TM Forum Member
    Posted Sep 19, 2022 15:23

    Hi, 

    I'm working on replacing most of the object models defined in this version of the tmforum620 swagger spec with the object models found here. However, I notice that some of the models in the swagger file are not present in the datamodels site. For example:

    • ProductOfferingRelationship
    • POPAlteration
    • POPCharge

      Example: ProductOffering from the swagger. Contains ProductOfferingRelationship

      "ProductOffering": {
      				"type": "object",
      				"properties": {
      					"id": {
      						"type": "string",
      						"description": "Unique identifier of the productOffering"
      					},
      					"href": {
      						"type": "string",
      						"description": "Reference of the ProductOffering"
      					},
      					"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."
      					},
      					"lastUpdate": {
      						"type": "string",
      						"description": "Date and time of the last update",
      						"format": "date-time"
      					},
      					"lifecycleStatus": {
      						"type": "string",
      						"description": "Used to indicate the current lifecycle status"
      					},
      					"name": {
      						"type": "string",
      						"description": "Name of the productOffering"
      					},
      					"statusReason": {
      						"type": "string",
      						"description": "A string providing a complementary information on the value of the lifecycle status attribute."
      					},
      					"version": {
      						"type": "string",
      						"description": "ProductOffering version"
      					},
      					"agreement": {
      						"type": "array",
      						"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.",
      						"items": {
      							"$ref": "#/components/schemas/AgreementRef"
      						}
      					},
      					"attachment": {
      						"type": "array",
      						"description": "Complements the description of an element (for instance a product) through video, pictures...",
      						"items": {
      							"$ref": "#/components/schemas/AttachmentRefOrValue"
      						}
      					},
      					"bundledProductOffering": {
      						"type": "array",
      						"description": "A type of ProductOffering that belongs to a grouping of ProductOfferings made available to the market. It inherits of all attributes of ProductOffering.",
      						"items": {
      							"$ref": "#/components/schemas/BundledProductOffering"
      						}
      					},
      					"category": {
      						"type": "array",
      						"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.",
      						"items": {
      							"$ref": "#/components/schemas/CategoryRef"
      						}
      					},
      					"channel": {
      						"type": "array",
      						"description": "The channel defines the channel for selling product offerings.",
      						"items": {
      							"$ref": "#/components/schemas/ChannelRef"
      						}
      					},
      					"marketSegment": {
      						"type": "array",
      						"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.",
      						"items": {
      							"$ref": "#/components/schemas/MarketSegmentRef"
      						}
      					},
      					"place": {
      						"type": "array",
      						"description": "Place defines the places where the products are sold or delivered.",
      						"items": {
      							"$ref": "#/components/schemas/PlaceRef"
      						}
      					},
      					"prodSpecCharValueUse": {
      						"type": "array",
      						"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.",
      						"items": {
      							"$ref": "#/components/schemas/ProductSpecificationCharacteristicValueUse"
      						}
      					},
      					"productOfferingPrice": {
      						"type": "array",
      						"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.",
      						"items": {
      							"$ref": "#/components/schemas/ProductOfferingPriceRefOrValue"
      						}
      					},
      					"productOfferingRelationship": {
      						"type": "array",
      						"description": "A relationship between this product offering and other product offerings.",
      						"items": {
      							"$ref": "#/components/schemas/ProductOfferingRelationship"
      						}
      					},
      					"productOfferingTerm": {
      						"type": "array",
      						"description": "A condition under which a ProductOffering is made available to Customers. For instance, a productOffering can be offered with multiple commitment periods.",
      						"items": {
      							"$ref": "#/components/schemas/ProductOfferingTerm"
      						}
      					},
      					"productSpecification": {
      						"$ref": "#/components/schemas/ProductSpecificationRef"
      					},
      					"resourceCandidate": {
      						"$ref": "#/components/schemas/ResourceCandidateRef"
      					},
      					"serviceCandidate": {
      						"$ref": "#/components/schemas/ServiceCandidateRef"
      					},
      					"serviceLevelAgreement": {
      						"$ref": "#/components/schemas/SLARef"
      					},
      					"validFor": {
      						"$ref": "#/components/schemas/TimePeriod"
      					},
      					"@baseType": {
      						"type": "string",
      						"description": "When sub-classing, this defines the super-class"
      					},
      					"@schemaLocation": {
      						"type": "string",
      						"description": "A URI to a JSON-Schema file that defines additional attributes and relationships",
      						"format": "uri"
      					},
      					"@type": {
      						"type": "string",
      						"description": "When sub-classing, this defines the sub-class Extensible name"
      					}
      				},
      				"description": "Represents entities that are orderable from the provider of the catalog, this resource includes pricing information."
      			},

      Example: ProductOffering from the datamodels site. Does not contain ProductOfferingRelationship

       "ProductOffering": {
            "$id": "#ProductOffering",
            "description": "Represents entities that are orderable from the provider of the catalog, this resource includes pricing information.",
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "description": "Description of the productOffering"
              },
              "href": {
                "type": "string",
                "description": "Reference of the ProductOffering"
              },
              "id": {
                "type": "string",
                "description": "Unique identifier 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."
              },
              "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"
              },
              "statusReason": {
                "type": "string",
                "description": "A string providing a complementary information on the value of the lifecycle status attribute."
              },
              "validFor": {
                "$ref": "../Common/TimePeriod.schema.json#TimePeriod",
                "description": "The period for which the productOffering is valid"
              },
              "version": {
                "type": "string",
                "description": "ProductOffering version"
              },
              "place": {
                "type": "array",
                "items": {
                  "$ref": "../Common/PlaceRef.schema.json#PlaceRef"
                },
                "description": "Place defines the places where the products are sold or delivered."
              },
              "serviceLevelAgreement": {
                "$ref": "../EngagedParty/SLARef.schema.json#SLARef",
                "description": "A service level agreement (SLA) is a type of agreement that represents a formal negotiated agreement between two parties designed to create a common understanding about products, services, priorities, responsibilities, and so forth. The SLA is a set of appropriate procedures and targets formally or informally agreed between parties in order to achieve and maintain specified Quality of Service."
              },
              "productSpecification": {
                "$ref": "../Product/ProductSpecificationRef.schema.json#ProductSpecificationRef",
                "description": "A ProductSpecification 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."
              },
              "channel": {
                "type": "array",
                "items": {
                  "$ref": "../Common/ChannelRef.schema.json#ChannelRef"
                },
                "description": "The channel defines the channel for selling product offerings."
              },
              "serviceCandidate": {
                "$ref": "../Service/ServiceCandidateRef.schema.json#ServiceCandidateRef",
                "description": "ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog."
              },
              "category": {
                "type": "array",
                "items": {
                  "$ref": "../Product/CategoryRef.schema.json#CategoryRef"
                },
                "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": "../Resource/ResourceCandidateRef.schema.json#ResourceCandidateRef",
                "description": "A resource candidate is an entity that makes a ResourceSpecification available to a catalog."
              },
              "productOfferingTerm": {
                "type": "array",
                "items": {
                  "$ref": "../Product/ProductOfferingTerm.schema.json#ProductOfferingTerm"
                },
                "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": "../Product/ProductOfferingPriceRef.schema.json#ProductOfferingPriceRef"
                },
                "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": "../EngagedParty/AgreementRef.schema.json#AgreementRef"
                },
                "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."
              },
              "attachment": {
                "type": "array",
                "items": {
                  "$ref": "../Common/AttachmentRefOrValue.schema.json#AttachmentRefOrValue"
                },
                "description": "Complements the description of an element (for instance a product) through video, pictures..."
              },
              "marketSegment": {
                "type": "array",
                "items": {
                  "$ref": "../MarketingSales/MarketSegmentRef.schema.json#MarketSegmentRef"
                },
                "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."
              },
              "bundledProductOffering": {
                "type": "array",
                "items": {
                  "$ref": "../Product/BundledProductOffering.schema.json#BundledProductOffering"
                },
                "description": "A type of ProductOffering that belongs to a grouping of ProductOfferings made available to the market. It inherits of all attributes of ProductOffering."
              },
              "prodSpecCharValueUse": {
                "type": "array",
                "items": {
                  "$ref": "../Product/ProductSpecificationCharacteristicValueUse.schema.json#ProductSpecificationCharacteristicValueUse"
                },
                "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."
              }
            },
            "allOf": [
              {
                "$ref": "../Common/Entity.schema.json#Entity"
              }
            ]
          }


      But all of these are also present in the pdf file for tmforum 620. The reason I want to use the datamodels version of the object models is so i can use inheritance properly when creating my own custom objects. What should i do in this regard? Are the data models outdated? Or are they what we should be using as a standard? I noticed that the swagger file is from March 2021 and the datamodels haven't been updated since 2020.

      I'd appreciate any help.

      Thank you.



      ------------------------------
      Asad Nawaz
      T-Mobile USA
      ------------------------------


    • 2.  RE: TMF620 - ProductOfferingRelationship exists in Swagger file but not in the datamodels

      TM Forum Member
      Posted Oct 02, 2022 08:03
      Hi Asad
      I don't know what the current state of the data model site is. I am pretty sure that it is not considered normative. Your first and only port of call should be the published assets at the API table.
      I understand why you want to use the data model, but for as long as we don't have a defined and supported means of publication, I strongly advise you not to use it.
      Sorry

      ------------------------------
      Jonathan Goldberg
      Amdocs Management Limited
      Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
      ------------------------------



    • 3.  RE: TMF620 - ProductOfferingRelationship exists in Swagger file but not in the datamodels

      TM Forum Member
      Posted Oct 21, 2022 13:11

      Hey there Jonathan,

      Sorry for the late reply, I was out of the country. So if i'm going to be using the published swaggers as the source of truth, how do i do inheritance? I'm using the swagger file to generate classes in Java, but when I do something like this: 

      "CategoryExtension":{
                      "type": "object",
                      "properties":{
                          "productType": {
                              "$ref": "#/components/schemas/ProductType"
                              },
                          "productSubType": {
                              "$ref": "#/components/schemas/ProductSubType"
                              },
                          "productClassification": {
                              "$ref": "#/components/schemas/ProductClassification"
                              },
                          "level": {
                              "maxLength": 100,
                              "minLength": 0,
                              "pattern": "^[\\S ]+$",
                              "type": "string",
                              "description": "Level for Account or Device Level of this product"
                              },
                          "supportedAcctType": {
                              "type": "string",
                              "description": "Indicates Account Types",
                              "example": "STANDARD",
                              "enum": [
                                  "STANDARD",
                                  "ESSENTIAL",
                                  "PRO",
                                  "ENTERPRISE",
                                  "ADVANTAGE",
                                  "BOTH",
                                  "PREPAID"
                                  ]
                              }
                          },
                      "allOf": [
      					{
      					  "$ref": "#/components/schemas/Category"
      					}
      				  ]
                  },

      I only get composition due to "allOf", but i want inheritance. I want my code to say:

      public class CategoryExtension extends Category

      However, it only generates a separate class "CategoryExtension". I know that the common models in the datamodels site i mentioned in the original question has a discriminator property based on the "@type" field on the Entity object. How should one go about approaching this?



      ------------------------------
      Asad Nawaz
      T-Mobile USA
      ------------------------------



    • 4.  RE: TMF620 - ProductOfferingRelationship exists in Swagger file but not in the datamodels

      TM Forum Member
      Posted Oct 23, 2022 02:15
      Hi Asad
      I'm afraid I know nothing really about code generators.
      The @type used as discriminator will come into its own in v5, when we support swagger/oas 3, with the oneOf directive.
      We've already published draft oas files for v5 ​in the early access table here https://projects.tmforum.org/wiki/pages/viewpage.action?pageId=128855518
      Hope it helps

      ------------------------------
      Jonathan Goldberg
      Amdocs Management Limited
      Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
      ------------------------------



    • 5.  RE: TMF620 - ProductOfferingRelationship exists in Swagger file but not in the datamodels

      TM Forum Member
      Posted Oct 24, 2022 10:44

      Hi Johnathan,

      Thanks for the reply. V5 is something that we're definitely going to keep an eye on! My final question would be: Is it acceptable to be able to modify the existing models so that I can use the discriminator property with them right now? This would be "our" version of TMF620. We're not changing the core definition of the models, but adding the ability to extend and distinguish between two custom models that extend one TMF620 Model. Example:

      "Extensible": {
                      "type": "object",
                      "required": [
                        "@type"
                      ],
                      "description": "Base extensible schema for use in TMForum Open-APIs",
                      "discriminator": {
                        "propertyName": "@type"
                      },
                      "properties": {
                        "@baseType": {
                          "type": "string",
                          "description": "When sub-classing, this defines the super-class",
                          "example": "Place"
                          },
                      "@schemaLocation": {
                          "type": "string",
                          "description": "A URI to a JSON-Schema file that defines additional attributes and relationships",
                          "format": "uri"
                          },   
                        "@type": {
                          "type": "string",
                          "description": "When sub-classing, this defines the sub-class entity name",
                          "example": "VendorProductOffering"
                        }
                      }
                    }
                  },



      ------------------------------
      Asad Nawaz
      T-Mobile USA
      ------------------------------