DEV Community: Tristan Cartledge

A better way to handle OpenAPI in Go. 🛠️

Tristan Cartledge — Mon, 15 Dec 2025 01:11:42 +0000

Under the Hood: Building a High-Performance OpenAPI Parser in Go | Speakeasy

An engineering deep dive into the architecture of Speakeasy's new OpenAPI library for Go. Learn how we solved challenges with dynamic types, reference resolution, and performance at scale—and why it's becoming the default choice for OpenAPI work in Go.

speakeasy.com

OpenAPI Tips - Data Type & Formats

Tristan Cartledge — Mon, 19 Dec 2022 11:07:06 +0000

The Problem

The OpenAPI spec is best known for descriptions of RESTful APIs, but it’s designed to be capable of describing any HTTP API whether that be REST, or something more akin to RPC based calls.

That leads to the spec having a lot of flexibility baked-in: there's a lot of ways to achieve the exact same result that are equally valid in the eyes of the spec. Because of this, the OpenAPI documentation is very ambiguous when it comes to how you should define your API.

That’s why we’re taking the time to eliminate some of the most common ambiguities that you’ll encounter when you build your OpenAPI spec. In this case we’ll be taking a look at how to effectively use data types in your OpenAPI 3.0.X spec.

Note: We will cover the differences introduced by 3.1 in a future post.

Recommended Practices

The OpenAPI Spec gives you plenty of options for describing types, but also a lot of options to describe them loosely. Loose is fine if your goal is to have a spec that is valid, but if you are using your OpenAPI document to generate code, documentation or other artifacts, loose will get you into trouble.

Describe your types as accurately as possible; you will not only improve the documentation of your API (reducing ambiguity for end-users), but will give as much information as possible to any tools you might be using for generation. Concretely, we recommend that you:

Describe your types as explicitly as possible by using the OpenAPI defined formats.
Use additional validation attributes as much as possible: mark properties as required, set readOnly/writeOnly, and indicate whenever fields are nullable.

Below, we will step through the different types available in OpenAPI and explain how to use formats, patterns and additional attributes to give you a spec that is both descriptive and explicit.

The Data Types

In addition to an object type, for custom type definitions, the OpenAPI Specification supports most of the “primitive” types and objects you would expect:

For each of these primitive types, there is a set of commonly-used formats (i.e. date format for string) which you can designate to enforce additional constraints on the values of a schema or field. There is also the option of associating a nullable attribute. These options lead to a number of different possibilities for describing your data.

The OpenAPI Spec also includes the ability to describe more complex relationships between types using the oneOf/anyOf/allOf attributes and providing the ability to describe enums but we will leave the discussion of them to a future blog post.

For now let's explore the various types and format options available.

string

Of the primitive types (ignoring the object type) , the string type is the most flexible type available, and the one you will use most. In addition to being able to represent other types (such as “true”, “100”, “{\“some\”: \”object\”}”), it supports a number of formats that overlay constraints on the data represented. If you are using the OpenAPI spec for code generation, this is important for correctly mapping to types in various languages.

Formats

The string type via the OpenAPI Specification officially supports the below formats:

type	format	explanation	example
string	date	An RFC3339 formatted date	“2022-01-30”
string	date-time	An RFC3339 formatted date- time string	“2019-10-12T07:20:50.52Z”
string	password	Provides a hint that the string may contain sensitive information.	“mySecretWord1234”
string	byte	Any integer number	“U3BlYWtlYXN5IG1ha2VzIHdvcmtpbmcgd2l0aCBBUElzIGZ1biE=”
string	binary	Binary data, used to represent the contents of a file.	“01010101110001”

The format attribute can also be used to describe a number of other formats the string might represent but outside the official list above, those formats might not be supported by tooling that works with the OpenAPI Spec, meaning that they would be provided more as hints to end-users of the API:

email
uuid
uri
hostname
ipv4 & ipv6
and others

Below are some examples of describing various string types:

# A basic string
schema:
    type: string

# A string that represents a RFC3339 formatted date-time string
schema:
    type: string
    format: date-time

# A string that represents a enum with the specified values
schema:
    type: string
    enum:
      - "one"
      - "two"
      - "three"

# A string that represents a file
schema:
    type: string
    format: binary

Patterns

The string type also has an associated pattern attribute that can be provided to define a regular expression that should be matched by any string represented by that type. The format of the regular expression is based on Javascript and therefore could describe regular expressions that might not be supported by various tools or target languages, so make sure to check the compatibility with your intended targets.

Example of a string defined with a regex pattern:

# A string that must match the specified pattern
schema:
    type: string
    pattern: ^[a-zA-Z0-9_]*$

number/integer

The number/integer types allows the describing of various number formats through a combination of the type and format attribute, along with a number of attributes for validating the data, the spec should cover most use cases.

Available formats are:

type	format	explanation	example
number		Any number integer/float at any precision.	`10` or `1.9` or `9223372036854775807`
number	float	32-bit floating point number.	`1.9`
number	double	64-bit floating point number.	`1.7976931348623157`
integer		Any integer number	`2147483647` or `9223372036854775807`
integer	int32	32-bit integer	`2147483647`
integer	int64	64-bit integer	`9223372036854775807`

Below are some examples of defining number/integer types:

# Any number
schema:
    type: number

# A 32-bit floating point number
schema:
    type: number
    format: float

# A 64-bit floating point number
schema:
    type: number
    format: double

# Any integer
schema:
    type: integer

# A 32-bit integer
schema:
    type: integer
    format: int32

# A 64-bit integer
schema:
    type: integer
    format: int64

Various tools that consume an OpenAPI spec may treat a number/integer without a format attribute as a type capable of holding the closest representation of that number in the target language. For example, a number might be represented by a double, and an integer by an int64. Therefore, it’s recommended that you be explicit with the format of your number type and always populate the format attribute.

The number type also has some optional attributes for additional validation:

minimum - The minimum inclusive number the value should contain.
maximum - The maximum inclusive number the value should contain.
exclusiveMinimum - Make the minimum number exclusive.
exclusiveMaximum - Make the maximum number exclusive.
multipleOf - Specify the number/integer is a multiple of the provided value.

Some examples are below:

# An integer with a minimum inclusive value of 0
schema:
    type: integer
    format: int32
    minimum: 10

# An integer with a minimum exclusive value of 0
schema:
    type: integer
    format: int32
    minimum: 0
    exclusiveMinimum: true

# A float with a range between 0 and 1
schema:
    type: number
    format: float
    minimum: 0
    maximum: 1

# A double with an exclusive maximum of 100
schema:
    type: number
    format: double
    maximum: 100
    exclusiveMaximum: true

# An 64 but integer that must be a multiple of 5
schema:
    type: integer
    format: int64
    multipleOf: 5

boolean

The boolean type is simple; it represents either true or false. Be aware that it doesn’t support other truthy/falsy values like: 1 or 0, an empty string “” or null. It has no additional attributes to control its format or validation.

# A boolean type
schema:
    type: boolean

array

The array type provides a way of defining a list of other types through providing an items attribute that represents the schema of the type contained in the array.

# An array of string
schema:
    type: array
    items:
        type: string

# An array of objects
schema:
    type: array
    items:
        type: object
        properties:
            name:
                type: string
            age:
                type: integer

# An array of arbitrary things
schema:
    type: array
    items: {}

The array type will support any schema that describes any other type in its items attribute including types using oneOf/anyOf/allOf attributes.

The array type also has some optional attributes for additional validation:

minItems - The minimum number of items the array must contain.
maxItems - The maximum number of items the array must contain.
uniqueItems - The array must contain only unique items.

# An array of floats that must contain at least 1 element.
schema:
    type: array
    items:
        type: number
        format: float
    minItems: 1

# An array of strings that must contain at most 10 elements.
schema:
    type: array
    items:
        type: string
    maxItems: 10

# An array of booleans that must contain exactly 3 elements.
schema:
    type: array
    items:
        type: boolean
    minItems: 3
    maxItems: 3

# An array of strings that must contain only unique elements.
schema:
    type: array
    items:
        type: string
    uniqueItems: true

object

The object type allows simple and complex objects, dictionaries and free form objects, along with a number of attributes to control validation.

Fully typed object

Fully typed objects can be described by providing a properties attribute that lists each property of the object and its associated type.

# A fully typed object
schema:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer
            format: int32
        active:
            type: boolean

# A fully typed object with a nested object
schema:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer
            format: int32
        active:
            type: boolean
        address:
            type: object
            properties:
                street:
                    type: string
                city:
                    type: string
                state:
                    type: string
                zip:
                    type: string

Objects with properties have access to some additional attributes that allow the objects to be validated in various ways:

required - A list of properties that are required. Specified at the object level.
readOnly - A property that is only available in a response.
writeOnly - A property that is only available in a request.

# A fully typed object with all fields required
schema:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer
            format: int32
        active:
            type: boolean
    required:
        - name
        - age
        - active

# A fully typed object with only one field required
schema:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer
            format: int32
        active:
            type: boolean
    required:
        - name

# A fully typed object with some field as read only
schema:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer
            format: int32
        active:
            type: boolean
            readOnly: true # This field is only returned in a response
    required:
        - name
        - age
        - active # This field will only be required in a response

# A fully typed object with some field as write only
schema:
    type: object
    properties:
        name:
            type: string
        age:
            type: integer
            format: int32
        active:
            type: boolean
        isHuman:
            type: boolean
            writeOnly: true # This field is only required in a request
    required:
        - name
        - age
        - active
        - isHuman # This field will only be required in a request

Using Object for Dictionaries

The object type can also be used to describe dictionaries/maps/etc that use strings for keys and support any value type that can be described by the OpenAPI Spec.

# A dictionary of string values
schema:
    type: object
    additionalProperties:
        type: string

# A dictionary of objects
schema:
    type: object
    additionalProperties:
        type: object
        properties:
            name:
                type: string
            age:
                type: integer
                format: int32

You can also describe dictionaries that will contain certain keys:

# A dictionary that must contain at least the specified keys 
schema:
    type: object
    properties:
        name:
            type: string # Must match type of additionalProperties
    required:
        - name        
    additionalProperties:
        type: string

When using the additionalProperties attribute you can also specify additional attributes to validate the number of properties in the object:

minProperties - The minimum number of properties allowed in the object.
maxProperties - The maximum number of properties allowed in the object.

For example:

# A dictionary of string values that has at least one key.
schema:
    type: object
    additionalProperties:
        type: string
    minProperties: 1

# A dictionary of string values that has at most 10 keys.
schema:
    type: object
    additionalProperties:
        type: string
    maxProperties: 10

# A dictionary of string values that has 1 key.
schema:
    type: object
    additionalProperties:
        type: string
    minProperties: 1
    maxProperties: 1

Free form objects

The object type can also be used to describe any arbitrary key/value pair (where the keys are still required to be strings).

# An arbitrary object/dictionary that can contain any value.
schema:
    type: object
    additionalProperties: true

# An alternate way to specify an arbitrary object/dictionary that can contain any value.
schema:
    type: object
    additionalProperties: {}

null

OpenAPI 3.0.X doesn’t support a null type but instead allows you to mark a schema as being nullable. This allows that type to either contain a valid value or null.

# A nullable string
schema:
    type: string
    nullable: true

# A nullable integer
schema:
    type: integer
    format: int32
    nullable: true

# A nullable boolean
schema:
    type: boolean
    nullable: true

# A nullable array
schema:
    type: array
    items:
        type: string
    nullable: true

# A nullable object
schema:
    type: object
    properties:
        foo:
            type: string
    nullable: true

OpenAPI Tips - How to Handle Auth

Tristan Cartledge — Tue, 01 Nov 2022 17:25:11 +0000

The Problem

The OpenAPI spec is best known for descriptions of RESTful APIs, but it's designed to be capable of describing any HTTP API whether that be REST or something more akin to RPC based calls. That leads to the spec having a lot of flexibility baked-in; there's a lot of ways to achieve the exact same result that are equally valid in the eyes of the spec. Because of this, the OpenAPI documentation is very ambiguous when it comes to how you should define your API. That's why we'd like to take the time to eliminate some of the most common ambiguities that you'll encounter when you build your OpenAPI spec. In this case we'll be taking a look at how to correctly configure auth in your OpenAPI spec.

What Authentication mechanisms are available?

OpenAPI supports a number of different options for API authentication, which can be daunting when first starting out. Before we give our thoughts on the different methods, it's worth highlighting that regardless of the method of authentication you choose, you should pair it with TLS. TLS encrypts the messages to and from your API, to protect you and your users from attack. Learn more about setting up TLS here. Some of the common types of authentication are listed below:

apiKey: This is the most common form of authentication for machine-to-machine (M2M) APIs and supports passing a pre-shared secret in a number of different ways i.e. either via the Authorization header (or another custom header), as a query parameter, or via a cookie. While this is probably the most commonly used mechanism, it is generally one of the least secure. This is especially true if the key is passed outside of headers or cookies (i.e. via query params as various logging mechanisms normally store query param information). The biggest security flaw is that most pre-shared secrets are long lived and if intercepted can be used until they are either revoked or expire (generally in a number of months or years). This risk is normally tolerated for M2M applications as the chance of interception (especially when using private VPCs/TLS and other mechanisms) is relatively low when compared to a key from a user's device traveling on a public network.
basic: This is a simple authentication mechanism baked into the HTTP protocol. It supports sending an Authorization header containing an encoded username and password. While this can be a relatively simple mechanism to get started with, if used incorrectly can risk leaking easy to decode passwords. It also shares a lot of the downsides of apiKeys below.
bearer: This scheme allows the passing of a token (most commonly a JWT) in the Authorization header. This is generally used for short lived tokens that are granted to the users of your API through an additional login mechanism. Using a JWT allows for the storage of additional metadata within the token which can be helpful for some use cases, such as storing scopes for permissions models.
oauth2: A popular open authentication mechanism that supports an authentication flow that allows servers to authenticate on behalf of a user or organization. While more generally used for authenticating clients and end-users it is quite often used in machine-to-machine applications as well, but is less popular due to the added complexity of the authentication flows. OAuth2 is considered more secure than other mechanisms due to its granted privileges through short lived tokens, that limit damage from intercepting the tokens.
openIdConnect: Is an authentication mechanism built on top of OAuth2 that allows obtaining identity information about the authenticating user via JWTs.

Global Authentication vs Endpoint Authentication

The OpenAPI specification allows you to describe all the above authentication mechanisms and more from the HTTP Authentication Scheme Registry.
Describing security in your OpenAPI document is then done through 1 of 2 different options:

Global security: the security you describe is available for all operations in your document.
Per operation security: when described it overrides any global level security described. Here is an example of describing security in the ways mentioned above:

openapi: 3.0.3
info:
  title: Example Security Definitions
  version: 1.0.0
servers:
  - url: http://api.prod.speakeasyapi.dev
# Here we are describing the Global security schemes used by the operations in this document
# This is a list of security schemes names defined in the components section
security:
  - APIKey: []
components:
  # The definition of the used security schemes
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /test:
    get:
      # The security schemes defined here will override the global security schemes for this operation
      security:
        - Bearer: []
      responses:
        200:
          description: OK
    # This operation used the global security schemes defined as it doesn't provide its own
    delete:
      responses:
        200:
          description: OK

The important parts of the above example are the security and securitySchemes sections. We will go into some details about how they are defined and the options available.

How To Describe Security

The security section is a list (actually a list of key-value pairs, but we will talk a bit more about that later) of security schemes that can be used to authenticate all operations or a particular operation (depending on the scope of the security list).
Below is an example of a number of different ways you can use the security section of your document:

# The below example shows a single mandatory scheme needed for the API
security:
  - APIKey: []
# The below example shows that one of the below schemes is required for the API 
security:
  - APIKey: []
  - Bearer: []
# The below example shows there is no security required for the API
# this is equivalent to not having a security section at all at the Global scope
# or disabling security at the per operation level
security: []
# The below example shows that security is optional for the API
# this may be used if an API provides additional functionality when authenticated
security: 
  - APIKey: []
  - {}
# The below example shows that certain scopes are required by the OAuth token used
# to authenticate the API
security:
  - OAuth:
    - read
    - write

The items in the list are key-value pairs with a name or key of a security scheme defined in the components section. We recommend giving them a boring name that explains what they are.
The values are an array of scopes used only by the oauth2 and openIdConnect type schemes, and define what scopes are needed for the API.
When used as shown above it provides a list of available schemes that can be used, with the end-user of the API being able to choose one of the available schemes to use to authenticate.
If more than one scheme is required to authenticate an API, then that is where additional pairs in the key-value pairs come in. See the example below:

# The below example shows 2 options for an end user to choose, as long as they use one or the other
# they will be able to access the API
security:
  - APIKey: []
  - Bearer: []
# The example below differs as it is a single option with multiple schemes
# Both the APIKey and SigningKey need to be used together to access the API
security:
  - APIKey: []
    SigningKey: []
# The example below shows multiple options for an end user to chose
# with one of them requiring the use of multiple schemes
security:
  - APIKey: []
    SigningKey: []
  - Bearer: []

Combining schemes like above give you the option to define AND/OR type functionality when it comes to the requirements of your API.

How To Describe Security Schemes

securitySchemes are the actual details of the options provided in the security sections of your document. The security schemes are components that are defined with the components section of your document. Below is an example of the 5 types of security schemes described above and how they are defined:

...
components:
  schemas:
    ...
  responses:
    ...
  # The definition of the used security schemes
  securitySchemes:
    BasicAuth: # An arbitrary scheme name, we recommend something descriptive
      type: http
      scheme: basic
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT # Optional token format
    APIKey:
      type: apiKey
      in: header # or query/cookie
      name: X-API-Key
    OAuth:
      type: oauth2
      flows: # Many different flows are available - https://spec.openapis.org/oas/v3.1.0#oauth-flows-object
        implicit:
          authorizationUrl: https://test.com/oauth/authorize
          scopes:
            read: Grants read access
            write: Grants write access
    OpenIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://test.com/.well-known/openid-configuration

Best Practices

I generally recommend considering developer experience and weighing this up against the security requirements of your API. Consider its use cases such as will it be called from another server? A client? Or a combination of both. Based on your needs then try to describe your security requirements in your OpenAPI document as simply as possible, if you can avoid multiple options or too many per operation differences then it will generally require less friction for your end-user to get up and running and start using your API. This is the main reason we still see pre-shared secrets (described by the apiKey type above) being the most ubiquitous option amongst APIs today, but if not managed correctly it can be one of the least secure options available.