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

Make your API implementations your own

Adding repeatable OpenAPI description updates with Overlays is a good way to get from a generic or rather vague API description to something that you can implement efficiently in your own projects. Especially with published standards that might be used in many different settings, it can be particularly valuable to adapt to your own needs.

In this example, we showed adding enums which is a great way to give your SDKs and validators clearer instructions on the values that should be expected. Don’t neglect the other fields, such as updating descriptions or adding meaningful examples that will help those implementing the API (human or machine) to have the context they need to be successful.