TS 29.580: MBSUserDataIngSessionPatch inconsistencies with use of NULL values

[davidjwbbc]

Context

TS 29.580 V18.7.0:

• Clause 5.3.2.2.2 states that, when creating an MBS User Data Ingest Session, there shall be:
  • "one or several MBS Distribution Session(s), within the "mbsDisSessInfos" attribute"
• Clause 5.3.2.4.2 describes the update process including:
  • "if an existing MBS Distribution Session shall be deleted, the AF shall include the corresponding map entry set to the value "NULL" within the "mbsDisSessInfos" attribute with the map key set to its string-based map key provisioned during the request that initially created the MBS Distribution Session.
• Clause 6.1.2.2.2 indicates that the MIME type for the update PATCH method is "application/merge-patch+json" and follows RFC 7396.
• Table 6.2.6.2.2-1 describes the MBSUserDataIngSession type
• Table 6.2.6.2.4-1 describes the MBSUserDataIngSessionPatch type
• Clause A.3 provides the OpenAPI YAML description of the MBSUserDataIngSessionPatch component

RFC 7396 describes the operations associated with the application/merge-patch+json MIME type

Description

There are a few of inconsistencies between the explanation of how to use the MBSUserDataIngSessionPatch during an HTTP PATCH method update operation on the MBS User Data Ingest Session and the specified OpenAPI structures.

The text in Clause 5.3.2.4.2 and the description in Table 6.2.6.2.4-1 for the mbsDisSessInfos field indicate that this field is a map containing the keys to be added, removed or replaced. The value of a map entry, identified by an existing key, is NULL to remove the MBSDistributionSessionInfo for that key and an MBSDistributionSessionInfo structure to add or replace an MBS Distribution Session Information.

The OpenAPI YAML in Clause A.3 does not match this description. Instead the OpenAPI states that the mbsDisSessInfos field itself may be NULL, indicating in a JSON merge patch (RFC 7396) that all MBSDistributionSessionInfos in the MBS User Data Ingest Session are to be removed. This contradicts the rule that there must be at least one MBSDistributionSessionInfo as stated in Clause 5.3.2.2.2. It also does not allow the values in the map to be NULL to provide the removal option.

The description in Table 6.2.6.2.4-1 and Clause 5.3.2.4.2 of replacing the whole MBSDistributionSessionInfo type in the MBS User Data Ingest Session when passed in the mbsDisSessInfos map also does not match the description of the JSON merge patch operation given in RFC 7386 as an omitted optional field in the MBSDistributionSessionInfo is intended to remove the field in the MBS User Data Ingest Session, but the RFC 7396 definition of the patch operation would leave the field alone. Should RFC 7396 operation be intended then any optional field in the MBSDistributionSessionInfo must also be nullable in order to indicate removal during an update.

The update procedure in Clause 5.3.2.4.2 states that MBS Distribution Sessions can be removed but does not say what should happen if the last MBS Distribution Session in the MBS User Data Ingest Session is removed or if that is not allowed. This also contradicts Clause 5.3.2.2.2 stating that there must be at least one MBS Distribution Session.

Suggested solution

Fix the mbsDisSessInfos null values by removing "nullable: true" from the field description in the OpenAPI and either:

1. Create an MBSDistributionSessionInfoRm component type with all optional fields having an appropriate ...Rm type and use this in the map in the OpenAPI YAML and Table 6.2.6.2.4-1 to maintain RFC 7396 compliance; or
2. Allow the map values to be NULL and drop the "application/merge-patch+json" type and RFC 7396 references (Clause 6.1.2.2.2 and OpenAPI YAML) as the operation is incompatible. The MIME type would just be "application/json".

Option 1 would require the creation of a MBSDistributionSessionInfoRm component type and all referenced child type for optional fields in TS29580_Nmbsf_MBSUserDataIngestSession.yaml and TS29571_CommonData.yaml files.

Option 2 represents the minimal changes with small changes needed only to TS29580_Nmbsf_MBSUserDataIngestSession.yaml.

Before ("mbsDisSessInfos" attribute of MBSUserDataIngSessionPatch):

        mbsDisSessInfos:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MBSDistributionSessionInfo'
          minProperties: 1
          nullable: true
          description: >
            Contains the requested modifications to one or more MBS Distribution Session(s) 
            composing the MBS User Data Ingest Session.
            The key of the map shall be any unique string encoded value.

With corrections:

        mbsDisSessInfos:
          type: object
          additionalProperties:
            allOf:
              $ref: '#/components/schemas/MBSDistributionSessionInfo'
            nullable: true
          minProperties: 1
          description: >
            Contains the requested modifications to one or more MBS Distribution Session(s) 
            composing the MBS User Data Ingest Session.
            The key of the map shall be any unique string encoded value.

[rjb1000]

@davidjwbbc: Please could you separate out the actPeriodsRepRule cardinality issue onto its own issue? (This seems logically unrelated.)

[rjb1000]

From TS 29.580:

if an existing MBS Distribution Session shall be deleted, the AF shall include the corresponding map entry set to the value "NULL" within the "mbsDisSessInfos" attribute with the map key set to its string-based map key provisioned during the request that initially created the MBS Distribution Session.

@davidjwbbc's interpretation:

The key value is NULL to remove the key...

One small detail: my reading of the specification text quoted above is slightly different from yours. To remove a Distribution Session from the map, I think the key of the map is set to the value originally provisioned, and the corresponding value is set to NULL.

[rjb1000]

@davidjwbbc wrote:

the OpenAPI states that the mbsDisSessInfos field itself may be NULL, indicating in a JSON merge patch (RFC 7396) that all MBSDistributionSessionInfos in the MBS User Data Ingest Session are to be removed. This contradicts the rule that there must be at least one MBSDistributionSessionInfo as stated in Clause 5.3.2.2.2.

Clause 5.3.2.2.2 only applies to the Create operation, and not to the Update operation. So maybe setting the mbsDisSessInfos attribute to NULL in an Update is fine after all?