TS 26.512 V17.9.0: Discrepancies between normative tables and OpenAPI YAML

[davidjwbbc]

Background

While performing the uplift to V17.9.1 for the 5G-MAG 5GMS Application Function it was noticed that the OpenAPI YAML for the MetricsReportingConfiguration.metricsReportingConfigurationId property does not match the description in clause 7.8.3 in that the read-only: true flag was missing.

This has prompted a comprehensive comparison of the normative specifications within clauses 7 and 11 and the OpenAPI YAML files provided in annex C. The review checks for each property in the APIs:

• The mandatory nature.
• Its usage (read-write, read-only or write-only).
• Any bounds described for the field (such as the number of items an array must hold or the minimum values for integers).

Problem description

Discrepancies between the normative specifications in TS 26.512 V17.9.1 and the OpenAPI YAML files described in annex C of the same document version are listed in the table below.

Object	Field	Clause/Table	Required	Usage	Bounds	YAML Clause	YAML Required	YAML Usage	YAML Bounds
M1QoSSpecification	maxBtrUl	6.4.3.4-1 (Mislabelled as 6.4.3.2-1)	No	Read-Only		C.2	No ✔	RW ✖	✔
M1QoSSpecification	maxBtrDl	6.4.3.4-1 (Mislabelled as 6.4.3.2-1)	No	Read-Only		C.2	No ✔	RW ✖	✔
ProvisioningSession	provisioningSessionId	7.2.3.1-1	Yes	Read-Only		C.3.1	Yes ✔	RW ✖	✔
ProvisioningSession	serverCertificateIds	7.2.3.1-1	No	Read-Only		C.3.1	No ✔	RW ✖	✔
ProvisioningSession	contentPreparation‌TemplateIds	7.2.3.1-1	No	Read-Only		C.3.1	No ✔	RW ✖	✔
ProvisioningSession	metricsReporting‌ConfigurationIds	7.2.3.1-1	No	Read-Only		C.3.1	No ✔	RW ✖	✔
ProvisioningSession	policyTemplateIds	7.2.3.1-1	No	Read-Only		C.3.1	No ✔	RW ✖	✔
ProvisioningSession	edgeResources‌ConfigurationIds	7.2.3.1-1	No	Read-Only		C.3.1	No ✔	RW ✖	✔
ProvisioningSession	eventDataProcessing‌ConfigurationIds	7.2.3.1-1	No	Read-Only		C.3.1	No ✔	RW ✖	✔
ContentHostingConfiguration	ingestConfiguration.pull	7.6.3.1-1	Yes	RW		C.3.5	No ✖	RW ✔	✔
ContentHostingConfiguration	ingestConfiguration.protocol	7.6.3.1-1	Yes	RW		C.3.5	No ✖	RW ✔	✔
ContentHostingConfiguration	distributionConfigurations.canonicalDomainName	7.6.3.1-1	No	Read-Only (AF assigned)		C.3.5	No ✔	RW ✖	✔
ContentHostingConfiguration	distributionConfigurations.baseURL	7.6.3.1-1	No	Read-Only (AF assigned)		C.3.5	No ✔	RW ✖	✔
ContentHostingConfiguration	distributionConfigurations.cachingConfigurations.cachingDirectives	7.6.3.1-1	Yes	RW		C.3.5	No ✖	RW ✔	✔
MetricsReportingConfiguration	metricsReportingConfigurationId	7.8.3-1	Yes	Read-Only (AF assigned)		C.3.7	Yes ✔	RW ✖	✔
EdgeResourcesConfiguration	edgeResourcesConfigurationId	7.10.3.1-1	Yes	Read-Only (AF assigned)		C.3.9	Yes ✔	RW ✖	✔
EdgeResourcesConfiguration	easRequirements.serviceContinuitySupport	7.10.3.3-1	N/A	N/A	No such field	C.3.9	No ✖	RW ✖	✖
EventDataProcessingConfiguration	eventDataProcessingConfigurationId	7.11.3-1	Yes	Read-Only (AF assigned)		C.3.10	Yes ✔	RW ✖	✔
EventDataProcessingConfiguration	dataAccessProfiles	7.11.3-1	Yes	RW	Min items=1	C.3.10	Yes ✔	RW ✔	None ✖
ServiceAccessInformation	clientMetricsReportingConfigurations.urlFilters	11.2.3.1‑1	No	Read-Only	Min items=1	C.4.1	Yes ✖	Read-only ✔	Min items=0 ✖
ConsumptionReport	mediaPlayerEntry	11.3.3.1-1	Yes	RW	AbsoluteUrl	C.4.2	Yes ✔	RW ✔	None ✖
DynamicPolicy	dynamicPolicyId	11.5.3.1-1	Yes	Read-Only		C.4.4	Yes ✔	RW ✖	✔
DynamicPolicy	enforcementMethod	11.5.3.1-1	Yes	Read-Only		C.4.4	Yes ✔	RW ✖	✔
DynamicPolicy	enforcementBitRate	11.5.3.1-1	Yes	Read-Only		C.4.4	Yes ✔	RW ✖	✔
NetworkAssistanceSession	naSessionId	11.6.3.1-1	Yes	Read-Only		C.4.5	Yes ✔	RW ✖	✔
NetworkAssistanceSession	recommendedQoS	11.6.3.1-1	No	Read-Only		C.4.5	No ✔	RW ✖	✔
NetworkAssistanceSession	notificationURL	11.6.3.1-1	No	Read-Only		C.4.5	No ✔	RW ✖	✔

The table indicates, in the last 3 columns, which attributes of the field do not match and need fixing by indicating that attribute with a ✔ if it currently matches the description and a ✖ if it does not match.

Proposed remedy

The various OpenAPI YAML descriptions in annex C should be modified to bring them in line with the descriptions of the fields from clauses 7 and 11.

[davidjwbbc]

This is a more comprehensive review than #102 as it includes bounds and required fields.

[rjb1000]

clientMetricsReportingConfigurations.urlFilters

All properties in the ServiceAccessInformation resource are effectively read-only already because the POST method is not supported on the Service Access Information API endpoint. So I propose not marking this one property as readOnly.

Fixing the cardinality and required status of this property is fine, though.

[rjb1000]

EASRequirements.serviceContinuitySupport

This property of the EdgeResourcesConfiguration resource appears to be a duplicate of EASRequirements.serviceContinuityScenarios, so I propose deleting EASRequirements.serviceContinuitySupport altogether.

@ibouazizi should shout if this is not the case.

Maybe it changed its name somewhere along the path of standardisation. The absence of a row in table 7.10.3.3-1 certainly suggests this explanation.

[rjb1000]

Initial CR drafted and content agreed by SA4 MBS SWG:

• TS 26.512
  • Rel-16: Decided not to fix.
  • Rel-17: CR0080 "[5GMS3, TEI17] Align OpenAPI YAML with normative descriptions" in S4aI240116.
  • Rel-18: Not impacted – APIs have moved to TS 26.510.

To be resubmitted to SA#130 (Orlando) meeting for SA4 agreement.