Open APIs

Hi all,

While going through TMF 622 Product Order Open API User Guide, we could observe that there are 2 associations between ProductOrderItem and OrderPrice with the names "itemTotalPrice" and "itemPrice". They also have same cardinality towards "OrderPrice" i.e. 0..*

We could also observe same description for both these fields in the user guide.

What is the distinction expected from TMF 622 perspective with respect to these 2 associations?

------------------------------
Varun Pandhi
Infosys
------------------------------

Hi Varun

You have highlighted a more general issue in the documentation for JSON schema. The "description" attribute with a basic JSON type describes the property. However, when the  property is a non-basic type, i.e. "$ref", then any other attributes on the property are ignored, including the "description", since the understanding is that "description" is taken from the referred schema. In your example, the schema for "OrderPrice". See this github issue in JSON schema for a discussion: https://github.com/json-schema-org/json-schema-spec/issues/239

Although our asset-generating tooling ignores the ignore directive and has honored "description" field on "$ref" properties, nevertheless API designers have not always provided a description.

And now to your specific query - OrderPrice is derived from an instantiation of ProductOfferingPrice (from the catalog). So if an order item instantiates a ProductOffering that has multiple ProductOfferingPrice, you would expect to see corresponding itemPrice for each ProductOfferingPrice.

The itemTotalPrice is supposed to aggregate the total prices from all order items contained in this order item, and there will be one itemTotalPrice for each price type (recurring and onetime).

Hope the above makes sense.

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

The ProductPrice can be used as described by Jonathan. this what you can also do:
since the relationship is 0..*, each single product can have multiple instances of itemTotalPrice to provide better (or legally required) pricing information to customers:

• Sum all on-time prices
• Sum all recurring prices
• rollup prices (only for composite products)
• Sum net prices by time period
• Sum net price for the first year
• etc

------------------------------
Kind regards,

Matthieu Hattab
Lyse Platform
------------------------------

Original Message:
Sent: Feb 29, 2024 14:42
From: Jonathan Goldberg
Subject: Two associations itemTotalPrice and itemPrice from ProductOrderItem towards OrderPrice

Hi Varun

You have highlighted a more general issue in the documentation for JSON schema. The "description" attribute with a basic JSON type describes the property. However, when the  property is a non-basic type, i.e. "$ref", then any other attributes on the property are ignored, including the "description", since the understanding is that "description" is taken from the referred schema. In your example, the schema for "OrderPrice". See this github issue in JSON schema for a discussion: https://github.com/json-schema-org/json-schema-spec/issues/239

Although our asset-generating tooling ignores the ignore directive and has honored "description" field on "$ref" properties, nevertheless API designers have not always provided a description.

And now to your specific query - OrderPrice is derived from an instantiation of ProductOfferingPrice (from the catalog). So if an order item instantiates a ProductOffering that has multiple ProductOfferingPrice, you would expect to see corresponding itemPrice for each ProductOfferingPrice.

The itemTotalPrice is supposed to aggregate the total prices from all order items contained in this order item, and there will be one itemTotalPrice for each price type (recurring and onetime).

Hope the above makes sense.

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