OpenAPI Extensibility Takes a Step Forward

Originally published on the RepreZen Blog.

OpenAPI is an extensible language. And over the past few days, I’ve been exploring new ways to make those language extensions more discoverable and easier to use.

The OpenAPI Specification is constructed as an object model, expressible in JSON or YAML syntax, to describe and document REST APIs. It defines a graph of object types and properties to model essential concepts like resources, methods, requests, responses, and message payloads.

Along with the predefined properties, most of the object types in Swagger‑OAS 2.0, and even more of them in OAS 3.0, allow specification extensions (f.k.a. “vendor extensions”), so you can attach additional information to those objects. Extension properties can have any legal name that starts with an x- prefix, and their values can be primitive or object-typed.

What can I do with Specification Extensions?

Specification extensions are useful! And they are widely used by OpenAPI 2.0 and 3.0 tool providers, code generators, platform integrations, and other components to embed specialized data, and support implementation-specific functionality. Mermade’s analysis of specification extensions found 1,184 distinct extension property names, used across 49,366 OpenAPI definitions.

For example, Microsoft Flow provides a set of OpenAPI extensions for custom connectors. Take a look at the following code snippet from their example, reformatted in YAML syntax. The x‑ms‑summary extension sets a list box label in the Flow UI, and the x‑ms‑dynamic-values binds the listID-dynamic path parameter to GetLists operation, so the UI can present this parameter as a dynamically populated drop-down list:

/api/lists/{listID-dynamic}:
    get:
      description: |
        Get items from a single list - uses dynamic Values
        and outputs dynamic-schema
      summary: 'Get''s items from the selected list '
      operationId: GetListItems
      parameters:
      - name: listID-dynamic
        type: string
        in: path
        description: Select List you want outputs from
        required: true
        x-ms-summary: Select List
        x-ms-dynamic-values:
          operationId: GetLists
          value-path: id
          value-title: name
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/DynamicResponseGetListSchema'

Other examples:

• Amazon API Gateway defines a set of specification extensions to adapt a back-end service to a client-facing API provided through the gateway. There are extension properties to control authorization, caching, custom validation, and other details of the Amazon API Gateway integration. An OpenAPI specification with these extensions can serve as a complete gateway configuration.
• APIs.guru uses specification extensions for its OpenAPI directory, so each API specification can be annotated with a language, origin, categories and other metadata.
• NSwag code generator for .NET uses an extension to specify symbolic constant names for enum values in a schema.

Extension Registration and Discovery

To this point, specification extensions have been entirely decentralized.

• Anyone can publish an OpenAPI 3.0 or 2.0 document with x-prefixed properties in any of the objects that allow them.
• Anyone can write software that produces or consumes those extension properties, and document the expected usage of those extensions for their users.
• Extending the prefix with a provider ID, like x‑ms‑… or x‑reprezen‑… is a good idea to avoid name clashes, but it’s not enforced, and there are many extensions that don’t do this.
• There are resources that list some of the documented OpenAPI extensions, but no official, centralized registry to coordinate efforts and make extensions discoverable.

Thankfully, that’s changing. The OpenAPI TDC has decided to create a specification extension registry, and I think we’ll most likely see this online within the next week or two. The registry concept, as discussed so far, is simple. It’s a community-managed markdown file with a table of known registrations. With active participation from software providers who define specification extensions, this should be a valuable resource for OpenAPI users and tool providers.

OK, but what about the editing experience?

Today’s OpenAPI editors tolerate extension properties, but don’t usually provide specialized code assist, tool tips, or validation for them. Specification extensions are kind of a second-class feature of the language, where most editors are concerned, unless the editor goes to the trouble of supporting specific extensions that we think are important, in a completely proprietary way.

The OAI specification extension registry, maybe with the help of a clever markdown processor, should allow tools like RepreZen API Studio and KaiZen Editor to offer users a list of available extension properties by name. It’s a good start.

But I think we can do better than that!

Semoasa— Specification Extension Metadata for OAS Annotations

I asked on last week’s TDC call if there’s any standard or proposed standard for a machine-readable description of specification extensions, that would allow us to provide a user experience much closer to what we provide for standard OpenAPI syntax — with context-sensitive content assist, validation, and other productivity features.

The answer came back that there is no such standard, as far as we know. So I took some time this weekend to draft one:

In the spirit of OpenAPI, Semoasa (pronounced “samosa”) is an open, vendor-neutral format for describing specification extensions. I think Semoasa can make specification extensions a whole lot easier to use. In particular:

• Schema — Extension providers can specify, in a standard JSON schema, what values each of their extension properties expect.
• Context — Extension providers can also specify the context for each exension property, as a list of OAS v2 and/or v3 object types that can be extended with these properties.
• Catalogs — Registries can aggregate and publish an entire catalog of extensions. Users can point their tools to a single registry, or even multiple registries, to get a consolidated list of available extensions.
• Namespace — Each extension property is defined within a namespace, to disambiguate duplicate names.

Semoasa is a draft, and it’s brand new. It needs to be validated, discussed, debated, improved, and eventually adopted by the OpenAPI community.

I think there’s an opportunity here to make specification extensions more of an essential and valuable part of the OpenAPI framework, and an important input into the evolution of OpenAPI itself. As certain specification extensions get broader adoption and tool support, they can become candidates for promotion into later revisions of the OpenAPI spec.

If you’d like to see this happen, please read the draft spec, post questions or comments in the issues list, and let us know what you think!

PREVIOUS POST

Topics: API, Swagger, OpenAPI, Open Source, Extensibility, Standards, SEMOASA