ContentHostingConfiguration.distributionConfigurations.supplementaryDistributionNetworks inconsistencies.

[davidjwbbc]

Description

From TS 26.512:

1. Table 7.6.3.1-1 states that the distributionConfigurations.supplementaryDistributionNetworks field is a "Array(Map(DistributionNetworkType -> DistributionMode)", this has an uneven number of brackets. The text suggests that this is a mappings list, so "Array(" probably should not be there.
2. Annex C.3.5 defines distributionConfigurations.supplementaryDistributionNetworks as an object with a "default" property whose value is a DistributionNetworkType and any other property whose value is a DistributionMode type. This is contradictory to the suggested structure in table 7.6.3.1-1.

The table suggests that this structure should look something like:

{
  "NETWORK_EMBMS": "MODE_HYBRID",
  "FUTURE_NETWORK_TYPE": "MODE_EXCLUSIVE"
}

However the OpenAPI in C.3.5 suggests that it would look like (where "default" is a mandatory property):

{
   "default": "NETWORK_EMBMS",
   "anything_i_want": "MODE_HYBRID"
}

I suspect that the first interpretation, from the table, is the correct one. Unfortunately this cannot be explicitly specified in OpenAPI as the type of the object property keys cannot be defined, they have to be a plain string. If this structure is wanted, then the only option is to document what the key type should be in the object description text.

(From discussion on this issue)
The alternative, in order to strongly type the two values, is to change this to an array of objects which have two mandatory fields, one for the distributionNetworkType and one for the distributionMode.

Suggested solution

1. Change the entry for distributionConfigurations.supplementaryDistributionNetworks in table 7.6.3.1-1 to say "Array(Object)" for the Data Type.
2. Add two extra rows in Table 7.6.3.1-1 after distributionConfigurations.supplementaryDistributionNetworks:

distributionNetworkType	DistributionNetworkType	1..1	Specifies the distribution network type for this mapping. Must be unique within this supplementaryDistributionNetworks array.
distributionMode	DistributionMode	1..1	Specifies the distribution mode to use with the distributionNetworkType.

3. Change the YAML in C.3.5 for TS26512_M1_ContentHostingProvisioning.yaml#components/schemas/DistributionConfiguration/supplementaryDistributionNetworks to:

supplementaryDistributionNetworks:
    type: array
    items:
        type: object
        properties:
            distributionNetworkType:
                $ref: '#/components/schemas/DistributionNetworkType'
            distributionMode:
                $ref: '#/components/schemas/DistributionMode'
        required:
          - distributionNetworkType
          - distributionMode

[rjb1000]

(Note that this issue does not affect Rel-16: it is a feature of Rel-17 onwards.)

[rjb1000]

The design intent here is a dictionary (associative array, hash map) with a predetermined set of valid index keys.

https://swagger.io/docs/specification/data-models/dictionaries/

[rjb1000]

If the index of the associative array cannot be strongly typed in OpenAPI, how about a simple array of objects that have two members: distributionNetworkType and distributionMode?

[davidjwbbc]

The array of objects with a pair of values would be:

supplementaryDistributionNetworks:
    type: array
    items:
        type: object
        properties:
            distributionNetworkType:
                $ref: '#/components/schemas/DistributionNetworkType'
            distributionMode:
                $ref: '#/components/schemas/DistributionMode'
        required:
          - distributionNetworkType
          - distributionMode

[rjb1000]

Yes, that's precisely what I had in mind, @davidjwbbc.

Thanks for saving me the trouble!

[rjb1000]

Latest draft CR for Rel-17 available to 5G-MAG members on Causeway as CDT0107.3GPP SA4#121 TS26.512 API corrections.

[rjb1000]

Formal CRs submitted to SA4#121:

• (This feature did not exist in Rel-16.)
• Rel-17 CR0028 in S4-221251.

[rjb1000]

The following Change Requests were agreed at SA4#121 Closing Plenary yesterday afternoon:

• TS 26.512:
  • Rel-16: (Not applicable.)
  • Rel-17: CR0028r2 S4-221606.

[rjb1000]

Change Request approved at SA#98-e:

• Rel-17: CR0028r2 in SP-221043.

[rjb1000]

New specifications published:

• Change not applicable to Rel-16.
• TS 26.512 V17.3.0.