Describing JSON Patch operations with OpenAPI

Featured image for sharing metadata for article

JSON Patch is a well-defined format for performing updates to HTTP objects, which allows you to avoid needing to design your own means for performing partial changes.

One thing that may not be super straightforward is how to define it in OpenAPI.

We can take inspiration from this Gist, and construct the following OpenAPI specification:

paths:
  "/the/path":
    patch:
      description: "..."
      operationId: "..."
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
components:
  schemas:
    PatchRequest:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/JSONPatchRequestAddReplaceTest'
          - $ref: '#/components/schemas/JSONPatchRequestRemove'
          - $ref: '#/components/schemas/JSONPatchRequestMoveCopy'
    JSONPatchRequestAddReplaceTest:
      type: object
      additionalProperties: false
      required:
        - value
        - op
        - path
      properties:
        path:
          description: A JSON Pointer path.
          type: string
        value:
          description: The value to add, replace or test.
        op:
          description: The operation to perform.
          type: string
          enum:
            - add
            - replace
            - test
    JSONPatchRequestRemove:
      type: object
      additionalProperties: false
      required:
        - op
        - path
      properties:
        path:
          description: A JSON Pointer path.
          type: string
        op:
          description: The operation to perform.
          type: string
          enum:
            - remove
    JSONPatchRequestMoveCopy:
      type: object
      additionalProperties: false
      required:
        - from
        - op
        - path
      properties:
        path:
          description: A JSON Pointer path.
          type: string
        op:
          description: The operation to perform.
          type: string
          enum:
            - move
            - copy
        from:
          description: A JSON Pointer path.
          type: string

Note that we use a separate schema for each option of the request, so we can i.e. autogenerate each portion of the request.

Written by Jamie Tanna's profile image Jamie Tanna on , and last updated on .

Content for this article is shared under the terms of the Creative Commons Attribution Non Commercial Share Alike 4.0 International, and code is shared under the Apache License 2.0.

#blogumentation #openapi #api #json-patch.

Also on:

This post was filed under articles.

Interactions with this post

Interactions with this post

Below you can find the interactions that this page has had using WebMention.

Have you written a response to this post? Let me know the URL:

Do you not have a website set up with WebMention capabilities? You can use Comment Parade.