The more I work on API standards, the more I realise how few teams understand that they can adopt the standards and, without breaking any contract, adapt them to make a strong interface for their own application. One of my favourite examples is to add enums where a standard interface cannot dictate the exact values, but in your own implementation it is very helpful to do so.

To start with, let's use this library book example snippet from an OpenAPI file - this is just the Components section:

components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: ISBN publication identifier
          format: isbn
          example: "9781250236210"
        title:
          type: string
          description: Book title
          example: "A Psalm for the Wild-Built"
        author:
          type: string
          description: Author's name
          example: "Becky Chambers"
        genre:
          type: string
          description: Genre of the book
          example: "Solarpunk"

That genre field at the end of the list is just a string - but in my library, I'm going to only offer a very specific set of genres, so I want to limit the values that can be used there. To that I'll use an OpenAPI Overlay.

Here's the Overlay:

overlay: "1.0.0"
x-speakeasy-jsonpath: rfc9535
info:
    title: "Set the genres list"
    version: "1.0.1"
actions:
    - target: $["components"]["schemas"]["Book"]["properties"]["genre"]
      update:
        enum:
            - Science Fiction
            - Fantasy
            - Speculative
            - Solarpunk
            - Philosophy

There are a few different tools that you can use to apply an Overlay - I've been using Speakeasy CLI a lot lately, mostly because I'm working with other OpenAPI tools and then using this tool's compare command to get an OpenAPI diff in Overlay format that I can reapply elsewhere.

Using Speakeasy CLI, the command to apply the overlay (let's say the file is overlay.yaml) to the OpenAPI description (imaginatively, mine is called library.openapi.yaml) is as follows:

speakeasy overlay apply --overlay=overlay.yaml --schema=library.openapi.yaml --out updated.openapi.yaml

The overlay updates the Book schema so that now the components section looks like this:

omponents:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          example: "9781250236210"
          description: ISBN publication identifier
          format: isbn
        title:
          type: string
          description: Book title
          example: "A Psalm for the Wild-Built"
        author:
          type: string
          description: Author's name
          example: "Becky Chambers"
        genre:
          type: string
          description: Genre of the book
          example: "Solarpunk"
          enum:
            - Science Fiction
            - Fantasy
            - Speculative
            - Solarpunk
            - Philosophical