Open APIs

• In case of PATCH if application/json is provided then the default rule will be to apply the same rules as for JSON merge.
• In case of JSON Patch [RFC6902] for partial updates "application/json-patch+json" media type MUST be used.
• In case of JSON PATCH Query, "application/json-patch-query+json" media type MUST be used.
• In case of PATCH as per https://tools.ietf.org/html/rfc7386 "application/merge-patch+json" MUST be used

• In case of PATCH if application/json is provided then the default rule will be to apply the same rules as for JSON merge.
• In case of JSON Patch [RFC6902] for partial updates "application/json-patch+json" media type MUST be used.
• In case of JSON PATCH Query, "application/json-patch-query+json" media type MUST be used.
• In case of PATCH as per https://tools.ietf.org/html/rfc7386 "application/merge-patch+json" MUST be used

The definitions of the v4 TMF APIs, which use swagger v2.0, do not include any definition of the JSON-PATCH schema (with the 'op', 'path', 'value', 'from' fields). Instead they assume that only JSON merge is supported, at least from swagger definition point of view. So, how can someone define the rest options in swagger? 

My understanding is that in swagger 2.0 this is not possible. In OAS 3.0 onwards this is supported and I can see that the v5 TMF APIs take advantage of this feature and define also the JSON-PATCH schema. However, if we haven't adopted v5 yet, but we are still in v4, what is the compliant way to support all patch options? 

• In case of PATCH if application/json is provided then the default rule will be to apply the same rules as for JSON merge.
• In case of JSON Patch [RFC6902] for partial updates "application/json-patch+json" media type MUST be used.
• In case of JSON PATCH Query, "application/json-patch-query+json" media type MUST be used.
• In case of PATCH as per https://tools.ietf.org/html/rfc7386 "application/merge-patch+json" MUST be used

Hi Panagiotis

JSON Patch is defined in RFC6902 and extended by TM Forum (JSON Patch Query) in TMF630 Part 5.  This pattern is supported in both V4 and V5 Open APIs and is compliant.  

From a V5 perspective, I presume you are referring to the update in the sample operations which now have an example of using JSON Patch Query.  We now have new OAS tooling at V5 that assists in the generation of these example JSON payloads.  As you have mentioned, the V4 tooling and sample operations were only provided using JSON merge.

The definitions of the v4 TMF APIs, which use swagger v2.0, do not include any definition of the JSON-PATCH schema (with the 'op', 'path', 'value', 'from' fields). Instead they assume that only JSON merge is supported, at least from swagger definition point of view. So, how can someone define the rest options in swagger? 

My understanding is that in swagger 2.0 this is not possible. In OAS 3.0 onwards this is supported and I can see that the v5 TMF APIs take advantage of this feature and define also the JSON-PATCH schema. However, if we haven't adopted v5 yet, but we are still in v4, what is the compliant way to support all patch options? 

• In case of PATCH if application/json is provided then the default rule will be to apply the same rules as for JSON merge.
• In case of JSON Patch [RFC6902] for partial updates "application/json-patch+json" media type MUST be used.
• In case of JSON PATCH Query, "application/json-patch-query+json" media type MUST be used.
• In case of PATCH as per https://tools.ietf.org/html/rfc7386 "application/merge-patch+json" MUST be used

Hi Dan,

the exact gap we're experiencing is related to the swagger files (OAS v2.0) used in the v4 of the TMF APIs. To make it more clear, the implementation on our end of a TMF API, e.g. of TMF632 Party Management API, is based on using the swagger file to automatically generate the classes, with their fields etc. So, the gap is that the swagger doesn't contain anything related to the JSON PATCH option (and the JSON PATCH Query either) for the PATCH method.

In the v5 of the TMF APIs, the JSON PATCH (as per RFC6902 and Content-Type: application/json-patch+json), as well as the JSON PATCH Query (as per TMF REST Guidelines Part 5 and Content-Type: application/json-patch-query+json) are explicitly defined in the OAS v3.0 file of the APIs. 

So, the question is if there is any way someone to define the JSON PATCH (as well as the JSON PATCH Query) and include this definition in the swaggers (OAS v2.0) of the TMF APIs

Example from v5 of TMF632:

Individual_MVO:
      description: The Individual to be patched
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Individual_MVO'
          examples:
            Individual_update_example_Implicit_Merge:
              $ref: '#/components/examples/Individual_update_example_Implicit_Merge_request'
        application/merge-patch+json:
          schema:
            $ref: '#/components/schemas/Individual_MVO'
          examples:
            Individual_update_example_Patch_Merge:
              $ref: '#/components/examples/Individual_update_example_Patch_Merge_request'
        application/json-patch+json:
          schema:
            $ref: '#/components/schemas/JsonPatchOperations'
          examples:
            Individual_update_example_JSON_Patch:
              $ref: '#/components/examples/Individual_update_example_JSON_Patch_request'
        application/json-patch-query+json:
          schema:
            $ref: '#/components/schemas/JsonPatchOperations'
          examples:
            Individual_update_example_JSON_Patch_Query:
              $ref: '#/components/examples/Individual_update_example_JSON_Patch_Query_request'
      required: true

JsonPatchOperations:
      description: JSONPatch Operations document as defined by RFC 6902
      type: array
      items:
        $ref: '#/components/schemas/JsonPatch'

JsonPatch:
      type: object
      description: A JSONPatch document as defined by RFC 6902
      required:
        - op
        - path
      properties:
        op:
          type: string
          description: The operation to be performed
          enum:
            - add
            - remove
            - replace
            - move
            - copy
            - test
        path:
          type: string
          description: A JSON-Pointer
        value:
          description: The value to be used within the operations.
        from:
          type: string
          description: A string containing a JSON Pointer value.

Thank you very much

Hi Panagiotis

JSON Patch is defined in RFC6902 and extended by TM Forum (JSON Patch Query) in TMF630 Part 5.  This pattern is supported in both V4 and V5 Open APIs and is compliant.  

From a V5 perspective, I presume you are referring to the update in the sample operations which now have an example of using JSON Patch Query.  We now have new OAS tooling at V5 that assists in the generation of these example JSON payloads.  As you have mentioned, the V4 tooling and sample operations were only provided using JSON merge.

The definitions of the v4 TMF APIs, which use swagger v2.0, do not include any definition of the JSON-PATCH schema (with the 'op', 'path', 'value', 'from' fields). Instead they assume that only JSON merge is supported, at least from swagger definition point of view. So, how can someone define the rest options in swagger? 

My understanding is that in swagger 2.0 this is not possible. In OAS 3.0 onwards this is supported and I can see that the v5 TMF APIs take advantage of this feature and define also the JSON-PATCH schema. However, if we haven't adopted v5 yet, but we are still in v4, what is the compliant way to support all patch options? 

• In case of PATCH if application/json is provided then the default rule will be to apply the same rules as for JSON merge.
• In case of JSON Patch [RFC6902] for partial updates "application/json-patch+json" media type MUST be used.
• In case of JSON PATCH Query, "application/json-patch-query+json" media type MUST be used.
• In case of PATCH as per https://tools.ietf.org/html/rfc7386 "application/merge-patch+json" MUST be used