OpenAPI operation to update a Chain Link Universe instance using JSON Merge Patch

patchUniverse.yaml

openapi: '3.1.0'
info:
  title: Update a Universe instance.
  description: Part of the Chain Links API.
  contact:
    name: David Biesack
    url: https://gist.github.com/DavidBiesack
  version: 0.0.0
tags:
  - name: Universes
    description: A universe in which Chains (fan fiction stories) exist
servers:
  - url: https://api.chainlinks.example.com
paths:
  /universes/{universeId}:
    parameters:
      - $ref: '#/components/parameters/universeIdPathParam'
    patch:
      summary: Patch a Universe instance.
      description: >-
        Update the mutable properties a Chain Link Universe instance.
        This update follows [JSON Merge Patch semantics](https://datatracker.ietf.org/doc/html/rfc7386).
      operationId: patchUniverse
      tags:
        -  Universes
      requestBody:
        description: Mutable properties of the universe to be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/universePatch'
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/universePatch'
      responses:
        '200':
          description: OK. The operation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/universe'
        '400':
          $ref: 'common.yaml#/components/responses/400'
        '404':
          $ref: 'common.yaml#/components/responses/404'

components:
  parameters:
    universeIdPathParam:
        name: universeId
        description: The unique `id` of an existing Universe instance.
        in: path
        required: true
        schema:
          $ref: 'common.yaml#/components/schemas/resourceId'
  schemas:

    mutableUniverseFields:
      title: Mutable Universe Fields
      description: Mutable properties of a Chain Link universe instance.
      properties:
        name:
          description: The name of the universe.
          minLength: 4
          maxLength: 64
        description:
          description: The description of the universe.
          minLength: 4
          maxLength: 512

 
    universe:
      title: Universe
      description: >-
        A universe in which authors can
        create new characters and new chains.
      type: object
      required:
        - id
        - url
        - name
        - description
        - createdAt
        - creator_url
        - characters_url
        - chains_url
      unevaluatedProperties: false
      properties:
        id:
          $ref: 'common.yaml#/components/schemas/resourceId'
        name:
          description: The name of the universe.
          minLength: 4
          maxLength: 64
        description:
          description: The description of the universe.
          minLength: 4
          maxLength: 512
        url:
          description: >-
            The URL of this universe instance
          type: string
          format: uri
        sourceUniverse_url:
          description: >-
            An optional universe that this one is derived from.
          type: string
          format: uri_reference
        createdAt:
          description: >-
            The date and time the author created universe,
            in RFC 3339 date-time format.
          type: string
          format: date-time
        creator_url:
          description: The URL of this universe's creator/author.
          type: string
          format: uri-reference
        characters_url:
          description: >-
            The URL of the API operation to list
             the characters that exist in this universe.
          type: string
          format: uri-reference
        chains_url:
          description: >-
            The URL of the API operation to list
            the chains that exist in this universe.
          type: string
          format: uri-reference

      example:
        id: https://api.chainlinks.example.com/universes/uni-489f34dhj37sghj
        url: /universes/uni-489f34dhj37sghj
        name: DragonTerr
        description: >-
           A world where dragons rule, but not without challengers.
        createdAt: '2023-08-23T18:34:10.444Z'
        creator_url: /authors/au-ndklxhjf8933x0
        characters_url: /characters?universe=uni-489f34dhj37sghj
        chains_url: /chains?universe=uni-489f34dhj37sghj

    universePatch:
      title: Universe Patch
      description: >-
        Request body for updating the mutable properties of
        a Chain Link universe instance.
      type: object
      unevaluatedProperties: false
      allOf:
        - $ref: '#/components/schemas/mutableUniverseFields'
      examples:
        - name: DragonTerr
        - description: >-
            A world where dragons rule, but not without challengers.
        - name: Dragon-Terr
          description: >-
            A world where dragons rule, but not without challengers.