Possible inconsistency in specification of Service Data Flow Description

[rjb1000]

Context

Clause 11.5.4 of TS 26.512 states:

The Dynamic Policy resource contains a serviceDataFlowDescription property which contains the service data flow template according to TS 23.503. The ServiceDataFlowDescription shall contain one of:

• a flowDescription object (including 5-Tuples, Type of Service, Security Parameter Index, etc.).
• a domainName.

This implies that flowDescription and domainName are mutually exclusive properties.

(A ServiceDataFlowDescription is also supplied by the Media Session Handler when creating a new Network Assistance session, per clause 11.6.3.1.)

Clause 6.4.3.2 specified the ServiceDataFlowDescription data type as having the above two properties, which are both specified as being optional. The following sentence appears at the end of this clause:

An object of type ServiceDataFlowDescription shall contain at least one property.

Problem description

The two normative statements highlighted above appear to be contradictory.

Suggested solution

1. Adjust the text at clause 6.4.3.2 to state that exactly one of the properties shall be present in ServiceDataFlowDescription.
2. Add some text to clause 11.6.4 (Network Assistance API) to match the text at clause 11.5.4 (Dynamic Policies API).
3. Adjust the OpenAPI at clause C.2 to specify that flowDescription and domainName are mutually exclusive using the oneOf YAML keyword.
   • https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

[rjb1000]

@tlohmar: please confirm that the suggested remedy was your original intent when specifying the Dynamic Policy instantiation API.

[tlohmar]

This implies that flowDescription and domainName are mutually exclusive properties.

hmm, the data type can be used for different purposes, thus, contains a 'at least one' of the properties. For Dynamic Policies, there is an additional constraint, i.e. 'at most one' / 'one of'. What is the inconsistency?

[rjb1000]

Ah... I see where you are coming from now, @tlohmar. You are saying that the data type is loosely defined on purpose at clause 6.4.3.2 to allow for future flexibility, but the additional constraint for Dynamic Policies is additionally specified on top of that in clause 11.5.4. And this explains why the constraint is not enforced by the OpenAPI specification of the ServiceDataFlowDescription data type.

This is rather unfortunate, in my opinion. It would be quite nice to enforce this in the OpenAPI syntax if possible. Otherwise, the implementer has to join the dots to enforce the constraint in custom code for each usage of the data type where the constraint applies.

The only other usage of the ServiceDataFlowDescription data type at the moment in TS 26.512 is for creating a new Network Assistance session (clause 11.6.3.1). The "eaxactly one of" constraint is not explicitly stated here, but I suspect it applies in just the same way as when instantiating a Dynamic Policy.

If we ever have a need to describe service data flows with both an IP Packet Filter Set and a domain name, I would suggest we define a different data type with different constraints. That makes things nice and explicit in the OpenAPI with no ambiguity. And these constraints can be enforced by the code automatically generated by compiling the OpenAPI YAML.

Hence, unless there is a good reason not to, I would advocate amending clause 6.4.3.2 and the OpenAPI syntax to make the "exactly one of" constraint explicit.

[rjb1000]

Any additional thoughts, @ibouazizi?

[tlohmar]

This is rather unfortunate, in my opinion. It would be quite nice to enforce this in the OpenAPI syntax if possible.

Yes, I agree. Would be better to have more in the OpenAPI syntax. My earlier comment was more on the reason for change The two normative statements highlighted above are contradictory.

[rjb1000]

Initial prototyping suggests that it's difficult to enforce oneOf in the OpenAPI YAML syntax without resorting to polymorphic data types. It works, but it is difficult to document.

I might just make the simple clarification in clause 6.4.3.2, so that at least the cardinality of the members is clearly specified in a common location.

[rjb1000]

Proposed clarification in clause 6.4.3.2 endorsed at post-SA4#124 ad hoc meeting:

• TS 26.512 CR0037 Rel-17 "[5GMS3, TEI17] Essential maintenance" in S4aI230105.

[rjb1000]

CR contributed to SA4#125 by @rjb1000:

• TS 26.512
  • Rel-16: CR0043 "Essential maintenance" in S4-231158.
  • Rel-17: CR0037r1 "Essential maintenance" in S4-231156.

[rjb1000]

CRs agreed at SA4#125:

• TS 26.512
  • Rel-16: CR0043r1 "Essential maintenance" in S4-231425.
  • Rel-17: CR0037r2 "Essential maintenance" in S4-231424.

[rjb1000]

CRs revised (YAML corrections) and approved at SA#101:

• TS 26.512
  • Rel-16: CR0043r2 "Essential maintenance" in SP-231082.
  • Rel-17: CR0037r3 "Essential maintenance" in SP-231053.

[rjb1000]

Approved changes published and available for download:

• TS 26.512 V16.11.0
• TS 26.512 V17.6.0