Open APIs

Expand all | Collapse all

Relationship between TargetProductSchema and Product.@type

Jump to Best Answer
  • 1.  Relationship between TargetProductSchema and Product.@type

    TM Forum Member
    Posted Apr 14, 2020 08:23
    Edited by Martin Honert Apr 16, 2020 08:26
    Hi tmforum community,

    I have some questions regarding the intended usage of the TargetProductSchema sub-resource (see TMF620):

    1) According to the documentation the TargetProductSchema is "the reference object to the schema and type of target product which is described by product specification."

    From my understanding, this is related to the concept of "schema based extension" as described in TMF630 (API Design Guidelines).
    So, I assume that the @type that is defined in the TargetProductSchema determines the @type of the Product resource (e.g. in the Product Inventory API) and thus the Product.@type attribute would be set to the @type attribute of the TargetProductSchema of the related ProductSpecification.
    Is this assumption correct?

    2) My second question is related to the external JSON schema that can be referenced via the @schemaLocation attribute.
    The APIs are generally specified in Swagger/Open API format and in order to add new sub-types of entities, we could add the polymorphic type definitions to the Swagger specifications.
    This means that the type hierarchy would be completely defined in the API specification.

    What would be the purpose of separate JSON schemas in this case?

    3) If the product attributes are defined using the CharacteristicSpec/Characteristic pattern in the Product Specification, then we can
    use the ProductSpecificationCharacteristicValueUse to select or restrict a specific value on the Product Offering level.
    Is there a similar mechanism that can be used for attributes that come from the static (schema-based) type definitions?

    Thanks and best regards,
    Martin


    ------------------------------
    Martin Honert
    Deutsche Telekom AG
    ------------------------------


  • 2.  RE: Relationship between TargetProductSchema and Product.@type
    Best Answer

    TM Forum Member
    Posted Apr 21, 2020 01:50
    Hi Martin
    Thanks for your important questions, trying to address them.

    First, we need to distinguish between the general polymorphism mechanism for TMF Open API entities, as against the specific schema-based catalog methodology that we have in Product Catalog (and also in the other catalogs such as Resource and Service).
    • The general mechanism would be used to extend e.g. ProductSpecification for your particular business needs. Let's suppose you decide to add a businessValue attribute (so a battery accessory might be Low, a high-end VPN might be High, etc.). You would have a DTProductSpecification with @type DTProductSpecification and @baseType ProductSpecification, and the @schemaLocation would point to a json schema file with property section such as {"businessValue": {"type":"string", "description": "business value of this spec"}}, and "allOf" referring to the original ProductSpecification schema. This extension applies of course to all product specifications.
    • The specific schema-based attributes in xxxxSpecification allow you to build specific strongly-typed specifications, with attributes instead of characteristics. So for Broadband, you might have BroadbandProductSpecification, pointing to a schema location that has a property section such as {"bandwidth": {"type":"number", "description": "bandwidth for this spec"}}, and you might even qualify with an enum restricting the valid values
    Currently the main drawback of the strongly-typed specification approach is that we have not (yet) defined how to encode the additional metadata that we have in the dynamic characteristics model - for example the CharacteristicUse that you refer to in the post. We have an open JIRA issue for this in the Open API team, so hopefully we will (eventually) get there.

    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.
    ------------------------------



  • 3.  RE: Relationship between TargetProductSchema and Product.@type

    TM Forum Member
    Posted Apr 27, 2020 06:46
    Hi Jonathan,

    thank you for the explanation.

    Best regards,
    Martin

    ------------------------------
    Martin Honert
    Deutsche Telekom AG
    ------------------------------



  • 4.  RE: Relationship between TargetProductSchema and Product.@type

    Posted 12 days ago
    Hi Jonathon

    Is my understanding correct that for these specific schema-based catalogs you would also use the "allOf" field within the target schema to extend ProductSpecification?

    Thanks
    Dan.

    ------------------------------
    Dan d'Albuquerque
    TO BE VERIFIED
    ------------------------------



  • 5.  RE: Relationship between TargetProductSchema and Product.@type

    TM Forum Member
    Posted 9 days ago
    I think yes, but it's really a matter of how you decide to implement the schema and how your backend is written to interpret it.
    It would be interesting to hear from anyone in the community who has actually implemented schema extensions according to TMF guidelines.

    ------------------------------
    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.
    ------------------------------