Decision Proposal 262 - Telco Product Reference Payloads

[CDR-API-Stream]

This decision proposal contains a recommendation for the candidate URIs and payloads for the Product data cluster for the telecommunications sector.

The decision proposal is embedded below:
Decision Proposal 262 - Product Data Payloads.pdf

This consultation will be open for feedback until the 5th September 2022.

[Telstra-CDR]

Hi All,
Telstra have reviewed the proposal and here are some feedback points on the proposed Telco Product Reference Payloads.

Page 2 – Cross Sector Alignment

“Specifically, it has been previously assumed that product data would not be presented from a single API set aligned to the designated organisation but that each entity that the customer has a relationship with (i.e. master brand) would present APIs independently”

1. Does the “Organisation” refer to the Data Holder / Legal Entity and the “Entity” refer to the data holder brand?

Page 3 - Designation Scope Fixed Line Internet Services

1. The definition excluded certain services such as Satellite based services unless delivered via nbn.

Page 4 – High Level Information

“Obtain information on a list of telecommunications products offered openly to the market”

1. Openly to market needs to be further clarified and expected in due course. Considerations required for offers such as employee only offers, offers that require a special qualification not generally available through our websites. E.g tailored offers for students/ pensioners, First responders, our partners etc.

Page 5 - Product List Data - Query Parameters

1. The domain of "Type" is too general and may be unmanageable for consumers. It would be hard to determine what product that they are interested in when they get the response.
   "Type" should be more detailed, or another attribute such as the Feature / Category introduced to enable differentiation between products.
2. Suggest consistency on the naming convention, Instances of use of a Kebab case and the camel case for query parameters
   Example: page-size vs billingType
3. Consider making type and brand at least mandatory to avoid large response payloads. Avoid larger response payloads where possible.
4. The level of “Brand” for filter is a bit unclear, a working example would be handy.
5. Page size request (default to 25) ,Suggestion to include a minimum page size

Page 5&6&7 - Response Payloads

1. Type scope covers mobile and fixed services, However this is limited to Broadband and Mobile, fixed has been omitted.

2. The definition of Type needs to be further expanded. The response payload doesn’t provide granularity and allow for differentiation on offers vs products vs promotional plans and hardware products, VAS etc. Feature / Category may need added to this payload.

3. For Type There needs to be an expansion of the Enum values beyond just Mobile and Broadband such as FIXED, Entertainment(Media) etc.

4. third party agent - the definition requires a bit more clarity, Consider catering for multiple Third Party Agents.

5. third party agent ID - is this an opaque/internal value or is there an official register for third party agents

6. EffectiveTo date -The assumption is the product/s are no longer exposed via the APIs beyond this date.

7. Usage - The word usage is not appropriate in this context. The definitions point to classification of the type of customer who owns the Product. Telstra is heading towards a segment agnostic view with no clear delineation between Personal and Business. We are the challenging the intent of this.

8. Additional Clarity is required on the IsBundle. When is a Product a Bundle? The classification may result in vagueness. Challenging the intent of this.

9. Billing Type - Consideration for Upfront Subscription services.

10. isContract does not specify repayment contract duration or terms impacting prices or final payout/ETC amounts. Are termsURI and pricingURI intended to cover this?

11. What is the different between URI and URIString?

12. Boolean TRUE if….Assume that capitalization is used for emphasis only and that JSON Boolean (true/false) is the expected response value here. Existing APIs do not seem to have the same emphasis. Comment applies to similar usage within the design proposal. (internal only)

13. General - Alignment of definitions to the TCP code is recommended.

Page 8 & 9 & 10 - Response Payloads Detail

1. Feature (Optional List of discounts available for the contract) – Is this supposed to be Discount and not Feature.
2. Feature[] - There appears to be two arrays that are very similar. When do we use one over the other? This refers to the use of this key in both bundle and plan.
3. When is a Product a bundle product? The example provided has feature category as Data, Voice, Text. Would we need to split our Mobile service Product into the services its provides? Likewise Fixed etc.
4. Category - expansion of the types to include other devices we offer as part of product we sell such as wearables and Entertainment Consoles etc. Device or Hardware perhaps are better enum values and also a catch all “Other”.
5. Pricing - Is this mandatory or optional? The description indicates optional.
6. Pricing - How do you envisage we model products/plans/pricing with optional add-ons? E.g. If we have 5 modems for the customer to select from, a security add-on, a static IP add-on, and a parental control add-on as a simple example. Are we supposed to generate all permutations?
7. Pricing - Assume hardware/device only products are not in scope as they are neither a mobile or broadband product.
8. Pricing - Consideration required and how promotional pricing ($x off for n months) or channel specific pricing or customer specific pricing or volume based pricing would apply.

[kirkycdr]

@Telstra-CDR thanks for your detailed response. We will provide an updated document. Below are initial responses

Hi All, Telstra have reviewed the proposal and here are some feedback points on the proposed Telco Product Reference Payloads.

Page 2 – Cross Sector Alignment

“Specifically, it has been previously assumed that product data would not be presented from a single API set aligned to the designated organisation but that each entity that the customer has a relationship with (i.e. master brand) would present APIs independently”

1. Does the “Organisation” refer to the Data Holder / Legal Entity and the “Entity” refer to the data holder brand?

DSB: Correct.

Page 3 - Designation Scope Fixed Line Internet Services

1. The definition excluded certain services such as Satellite based services unless delivered via nbn.

DSB: The rules outline this in Schedule 5 part 1 section 1.2

Page 4 – High Level Information

“Obtain information on a list of telecommunications products offered openly to the market”

1. Openly to market needs to be further clarified and expected in due course. Considerations required for offers such as employee only offers, offers that require a special qualification not generally available through our websites. E.g tailored offers for students/ pensioners, First responders, our partners etc.

DSB: Open to the market would mean available by a public digital channel

Page 5 - Product List Data - Query Parameters

1. The domain of "Type" is too general and may be unmanageable for consumers. It would be hard to determine what product that they are interested in when they get the response.
   "Type" should be more detailed, or another attribute such as the Feature / Category introduced to enable differentiation between products.

DSB: Type here reflects the high level types specified in the rules schedule 5 part 1

2. Suggest consistency on the naming convention, Instances of use of a Kebab case and the camel case for query parameters
   Example: page-size vs billingType

DSB: Good pickup. Will resolve

3. Consider making type and brand at least mandatory to avoid large response payloads. Avoid larger response payloads where possible.

DSB: The assumption is the majority of telco's would only have a single brand. Understand for larger providers this may not be the case. 

4. The level of “Brand” for filter is a bit unclear, a working example would be handy.

DSB: noted, will look to provide a relevant example.

5. Page size request (default to 25) ,Suggestion to include a minimum page size

DSB: We will consider the minimum page size suggestion. 25 is a relatively standard size.

Page 5&6&7 - Response Payloads

1. Type scope covers mobile and fixed services, However, this is limited to Broadband and Mobile, fixed has been omitted.

DSB: The intention was to align the types to the high level types specified in the rules schedule 5 part 1 In terms of broadband, agree it makes sense to differentiate types. Do you have a suggested list?

2. The definition of Type needs to be further expanded. The response payload doesn’t provide granularity and allow for differentiation on offers vs products vs promotional plans and hardware products, VAS etc. Feature / Category may need added to this payload.

DSB: VAS and Hardware may be features included in the product response but are not types in terms of products that are in scope.

3. For Type There needs to be an expansion of the Enum values beyond just Mobile and Broadband such as FIXED, Entertainment(Media) etc.

DSB: As discussed above

4. third party agent - the definition requires a bit more clarity, Consider catering for multiple Third Party Agents.

DSB: Noted. Can you provide anymore specific detail?

5. third party agent ID - is this an opaque/internal value or is there an official register for third party agents

DSB: Would expect this to be specific to the Data Holder

6. EffectiveTo date -The assumption is the product/s are no longer exposed via the APIs beyond this date.

DSB: What the API's return is determined by data holder implementation. But it would be expected not to return products that are no longer offered

7. Usage - The word usage is not appropriate in this context. The definitions point to classification of the type of customer who owns the Product. Telstra is heading towards a segment agnostic view with no clear delineation between Personal and Business. We are the challenging the intent of this.

DSB: Noted. However, these plans are still common in the industry. A suggestion may be an additional category of ALL as a default?

8. Additional Clarity is required on the IsBundle. When is a Product a Bundle? The classification may result in vagueness. Challenging the intent of this.

DSB: Bundle is at the interpretation of service providers that provide bundle offers through their digital channels. 

9. Billing Type - Consideration for Upfront Subscription services.

DSB: Good feedback. Noted.

10. isContract does not specify repayment contract duration or terms impacting prices or final payout/ETC amounts. Are termsURI and pricingURI intended to cover this?

DSB: Correct.

11. What is the different between URI and URIString?

DSB: Good pickup, a cut and paste error. These should all be URIString

12. Boolean TRUE if….Assume that capitalization is used for emphasis only and that JSON Boolean (true/false) is the expected response value here. Existing APIs do not seem to have the same emphasis. Comment applies to similar usage within the design proposal. (internal only)

DBB: Correct

13. General - Alignment of definitions to the TCP code is recommended.

DSB: Good feedback. Noted

Page 8 & 9 & 10 - Response Payloads Detail

1. Feature (Optional List of discounts available for the contract) – Is this supposed to be Discount and not Feature.
2. Feature[] - There appears to be two arrays that are very similar. When do we use one over the other? This refers to the use of this key in both bundle and plan.

DSB: Features are intended to be an array of features, this appears to be wrongly presented in the document.

3. When is a Product a bundle product? The example provided has feature category as Data, Voice, Text. Would we need to split our Mobile service Product into the services its provides? Likewise Fixed etc.

DSB: Bundle is at the interpretation of service providers that provide these offers through their digital channels. 

4. Category - expansion of the types to include other devices we offer as part of product we sell such as wearables and Entertainment Consoles etc. Device or Hardware perhaps are better enum values and also a catch all “Other”.

DSB: Good feedback. Noted.

5. Pricing - Is this mandatory or optional? The description indicates optional.

DSB: Noted. Will update the description to clearer.

6. Pricing - How do you envisage we model products/plans/pricing with optional add-ons? E.g. If we have 5 modems for the customer to select from, a security add-on, a static IP add-on, and a parental control add-on as a simple example. Are we supposed to generate all permutations?

DSB: There are feature arrays on both the Bundle and Plan objects.

7. Pricing - Assume hardware/device only products are not in scope as they are neither a mobile or broadband product.

DSB: Can you provide some examples?

8. Pricing - Consideration required and how promotional pricing ($x off for n months) or channel specific pricing or customer specific pricing or volume based pricing would apply.

DSB: The feature arrays were intended for this purpose and the additionalInformation section. Its possible we can provide a specific object in the pricing section. 

[kirkycdr]

Updates to the Decision Proposal

Decision Proposal 262 - Product Data Payloads.pdf

[perlboy]

• type is MOBILE and BROADBAND yet all other references are mobile and fixed internet. Broadband is ambiguous. Further there is very likely other types of product meeting the rules definition of product data.
• Unclear what value isBundle and isContract provide when detailed information can elaborate
• isContract doesn't appear to get expanded out to actual contract details which doesn't seem to achieve the draft rules product specific data inclusion of "information about the contractual arrangements in relation to the relevant product (for example, that it is a month-to-month contract or a 12-month contract);"
• Data Usage allowances don't appear to be included which doesn't meet the draft rules product specific data
• Accessibility data isn't included which doesn't meet the draft rules product specific data
• Products may have multiple third party "originators" (that's an odd term for telco) so this should probably be a list of objects structure
• usage field is a bit overloaded (telco talks about usage in lots of different contexts), perhaps purpose would be better?
• chargeAmount is needlessly prefixed, probably should be called simply amount like a majority of other similar payloads.
• No discounts described which doesn't meet the draft rules product specific data

[CDR-API-Stream]

Marking this consultation as No Decision Made. While the proposal and feedback for this consultation have been incorporated into the draft standards this is not yet a formal decision of the Chair.