TS 26.512: Discrepancy between tables and YAML for properties marked as read-only

[davidjwbbc]

Description

Issue #88 dealt with the discrepancy between Table 7.9.3.1-1 and the OpenAPI YAML in Annex C.3.8 with respect to some fields being marked as read-only, or described as being assigned by the 5GMS AF, in the Table but not marked as readOnly: true in the YAML. This becomes a problem with automatically generated code when the property is also a mandatory field, as the generated code will insist on the property being present in a request when it should not be present.

There are several other instances of properties being marked read-only in the Tables but not marked as such in the OpenAPI YAML definitions in the Annexes.

The following is a table of all the instances where a property is marked as read-only in a Table but not in the YAML.

Table	Property	Annex	Property Path under YAML /components/schemas/
6.4.3.4-1	maxBtrUl	C.2	M1QoSSpecification/maxBtrUl
6.4.3.4-1	maxBtrDl	C.2	M1QoSSpecification/maxBtrDl
7.2.3.1-1	provisioningSessionId	C.3.1	ProvisioningSession/provisioningSessionId
7.6.3.1-1	distributionConfigurations.canonicalDomainName	C.3.5	DistributionConfiguration/canonicalDomainName
7.6.3.1-1	distributionConfigurations.baseUrl	C.3.5	DistributionConfiguration/baseUrl
7.8.3.1-1	metricsReportingConfigurationId	C.3.7	MetricsReportingConfiguration/metricsReportingConfigurationId
7.10.3.1-1	edgeResourcesConfigurationId	C.3.9	EdgeResourcesConfiguration/edgeResourcesConfigurationId
7.11.3-1	eventDataProcessing‌ConfigurationId	C.3.10	EventDataProcessingConfiguration/eventDataProcessing‌ConfigurationId
11.5.3.1-1	dynamicPolicyId	C.4.4	DynamicPolicy/dynamicPolicyId
11.5.3.1-1	enforcementMethod	C.4.4	DynamicPolicy/enforcementMethod
11.5.3.1-1	enforcementBitRate	C.4.4	DynamicPolicy/enforcementBitRate
11.6.3.1-1	naSessionId	C.4.5	NetworkAssistanceSession/naSessionId
11.6.3.1-1	recommendedQoS	C.4.5	NetworkAssistanceSession/recommendedQoS
11.6.3.1-1	notficationURL	C.4.5	NetworkAssistanceSession/notficationURL

Suggested solution

Add the readOnly: true flag to all YAML properties where the same property is marked as read-only in the Data model Tables or noted that it is assigned by the 5GMS AF.

For types specified directly in the YAML, the addition of the readOnly: true will be sufficient, for example:

components:
  schemas:
    ObjectName:
      type: object
      description: An object description
      properties:
        simpleType:
          type: int

...would become...

components:
  schemas:
    ObjectName:
      type: object
      description: An object description
      properties:
        simpleType:
          readOnly: true
          type: int

For properties which reference a type defined elsewhere, where the the addition of the readOnly: true requires that the reference be placed in an allOf or anyOf section, for example:

components:
  schemas:
    ObjectName:
      type: object
      description: An object description
      properties:
        refdType:
          $ref: 'another_file.yaml#/components/schemas/RefdType'

...would become...

components:
  schemas:
    ObjectName:
      type: object
      description: An object description
      properties:
        refdType:
          readOnly: true
          allOf:
            $ref: 'another_file.yaml#/components/schemas/RefdType'

Additional context

See Issue #88 for the same change applied to the PolicyTemplates data model for TS 26.512 v17.6.0.

[rjb1000]

(These proposed changes affect TS 26.512 Rel-16 and Rel-17 only; the equivalent changes to the forthcoming TS 26.510 Rel-18 will be handled directly by the editor since this new specification is not yet under formal change control.)

[rjb1000]

Pushed into the next meeting cycle.

[rjb1000]

(These proposed changes affect TS 26.512 Rel-16 and Rel-17 only; the equivalent changes to the forthcoming TS 26.510 Rel-18 will be handled directly by the editor since this new specification is not yet under formal change control.)

I have now checked TS 26.510 Rel-18 and all fourteen of the properties list in the table are correctly marked as readOnly with the exception of DynamicPolicy/enforcementMethod and DynamicPolicy/enforcementMethod which have been merged into the simpler DynamicPolicy/qosEnforcement flag in Rel-18.

[rjb1000]

There wasn't sufficient bandwidth to address these discrepancies in TS 26.512 Rel-17 during the last meeting cycle.

We need to decide whether to go back and fix this.

Given that the reference implementation is currently based on Rel-17, there is an argument to maintain that release of TS 26.512.

Pushing this issue into the milestone for the next meeting cycle pending a decision.

[davidjwbbc]

#146 contains a more comprehensive list of the discrepancies between the OpenAPI YAML and the descriptions in Clauses 6 to 11 by also considering the cardinality and bounds imposed on the data fields as well as the read-only nature of the field.

[rjb1000]

Closing this old issue because #146 is now more comprehensive.