openapi: 3.1.0
info:
  title: Example OpenAPI definition
paths:
  /widgets:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WidgetPost"
      responses:
        201:
          $ref: "#/components/responses/WidgetResponse"
  /widgets/{id}:
    patch:
      parameters:
        - name: dataset_id
          in: path
          description: The UUID of a dataset
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json+merge-patch:
            schema:
              $ref: "#/components/schemas/WidgetMergePatch"
        required: true
      responses:
        200:
          $ref: "#/components/responses/WidgetResponse"
        404:
          description: The requested ID was not found
          content: {}
components:
  responses:
    WidgetResponse:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Widget"
  schemas:
    ResourceStatus:
      type: string
      description: The current state of this resource.
      example: new
      enum:
        - new
        - updating
        - ready
        - error
    Widget:
      type: object
      title: "Widgetter"
      required:
        - created_at
        - id
        - metadata
        - sku
        - status
        - updated_at
        - vendor_id
      properties:
        id:
          type: string
          format: uuid
          example: "994fc99e-fa9f-454b-a3de-c1966ae61533"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          $ref: "#/components/schemas/ResourceStatus"
        sku:
          type: string
        name:
          description: "The name of this widget."
          type: string
        vendor_id:
          type: string
          format: uuid
        metadata:
          $ref: "#/components/schemas/Metadata"
      additionalProperties: false
    WidgetPost:
      type: object
      title: "Widgetter"
      required:
        - metadata
        - sku
        - vendor_id
      properties:
        sku:
          type: string
        name:
          description: "The name of this widget."
          type: string
        vendor_id:
          type: string
          format: uuid
        metadata:
          $ref: "#/components/schemas/MetadataPost"
      additionalProperties: false
    WidgetPut:
      type: object
      title: "Widgetter"
      required:
        - metadata
      properties:
        name:
          description: "The name of this widget."
          type: string
        metadata:
          $ref: "#/components/schemas/MetadataPut"
      additionalProperties: false
    WidgetMergePatch:
      type: object
      title: "Widgetter"
      properties:
        name:
          description: "The name of this widget."
          oneOf:
            - type: string
              title: "Overwrite"
              description: "Pass this value to overwrite the existing value."
            - type: "null"
              title: "Clear"
              description: "Pass `null` to clear this field's existing value."
        metadata:
          $ref: "#/components/schemas/MetadataMergePatch"
      additionalProperties: false
    Metadata:
      type: object
      additionalProperties:
        type:
          - boolean
          - number
          - string
    MetadataPost:
      type: object
      additionalProperties:
        type:
          - boolean
          - number
          - string
    MetadataPut:
      type: object
      additionalProperties:
        type:
          - boolean
          - number
          - string
    MetadataMergePatch:
      type: object
      additionalProperties:
        type:
          - boolean
          - "null"
          - number
          - string