Skip to content

Latest commit

 

History

History
370 lines (282 loc) · 15.5 KB

1.1.0-dev.md

File metadata and controls

370 lines (282 loc) · 15.5 KB

Overlay Specification

Abstract

The Overlay Specification defines a document format for information that augments an existing [[OpenAPI]] description yet remains separate from the OpenAPI description's source document(s).

Version 1.1.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

This document is licensed under The Apache License, Version 2.0.

Introduction

The Overlay Specification is a companion to the [[OpenAPI]] Specification. An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description.

The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. An Overlay may be specific to a single OpenAPI description or be designed to apply the same transform to any OpenAPI description.

Definitions

Overlay

An Overlay is a JSON or YAML structure containing an ordered list of Action Objects that are to be applied to the target document. Each Action Object has a target property and a modifier type (update or remove). The target property is a [[RFC9535|RFC9535 JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.

Specification

Versions

The Overlay Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 1.0) SHALL designate the Overlay feature set. patch versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.

Note: Version 1.0.0 of the Overlay Specification was released after spending some time in draft and being implemented by a few early-adopting tool providers. Check with your tool provider for the details of what is supported in each tool.

Format

An Overlay document that conforms to the Overlay Specification is itself a JSON object, which may be represented either in [[RFC7159|JSON]] or [[YAML|YAML]] format.

All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

In order to preserve the ability to round-trip between YAML and JSON formats, [[YAML|YAML version 1.2]] is RECOMMENDED along with some additional constraints:

Relative References in URIs

Unless specified otherwise, all fields that are URI references MAY be relative references as defined by RFC3986.

Schema

In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

Overlay Object

This is the root object of the Overlay.

Fixed Fields
Field Name Type Description
overlay string REQUIRED. This string MUST be the version number of the Overlay Specification that the Overlay document uses. The overlay field SHOULD be used by tooling to interpret the Overlay document.
info Info Object REQUIRED. Provides metadata about the Overlay. The metadata MAY be used by tooling as required.
extends string URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to.
actions [Action Object] REQUIRED An ordered list of actions to be applied to the target document. The array MUST contain at least one value.

This object MAY be extended with Specification Extensions.

The list of actions MUST be applied in sequential order to ensure a consistent outcome. Actions are applied to the result of the previous action. This enables objects to be deleted in one action and then re-created in a subsequent action, for example.

The extends property can be used to indicate that the Overlay was designed to update a specific [[OpenAPI]] document. Where no extends is provided it is the responsibility of tooling to apply the Overlay document to the appropriate OpenAPI document(s).

In the following example the extends property specifies that the overlay is designed to update the OpenAPI Tic Tac Toe example document, identified by an absolute URI.

overlay: 1.0.0
info:
  title: Overlay for the Tic Tac Toe API document
  version: 1.0.0
extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
...

The extends property can also specify a relative URI reference.

overlay: 1.0.0
info:
  title: Overlay for the Tic Tac Toe API document
  version: 1.0.0
extends: './tictactoe.yaml'

Info Object

The object provides metadata about the Overlay. The metadata MAY be used by the clients if needed.

Fixed Fields
Field Name Type Description
title string REQUIRED. A human readable description of the purpose of the overlay.
version string REQUIRED. A version identifier for indicating changes to the Overlay document.

This object MAY be extended with Specification Extensions.

Action Object

This object represents one or more changes to be applied to the target document at the location defined by the target JSONPath expression.

Fixed Fields
Field Name Type Description
target string REQUIRED A RFC9535 JSONPath query expression selecting nodes in the target document.
description string A description of the action. [[CommonMark]] syntax MAY be used for rich text representation.
update Any If the target selects an object node, the value of this field MUST be an object with the properties and values to merge with the selected node. If the target selects an array, the value of this field MUST be an entry to append to the array. This field has no impact if the remove field of this action object is true.
remove boolean A boolean value that indicates that the target object or array MUST be removed from the the map or array it is contained in. The default value is false.

The result of the target JSONPath expression MUST be zero or more objects or arrays (not primitive types or null values). Should the target JSONPath result in selecting two or more nodes, they MUST be either all objects or all arrays.

To update a primitive property value such as a string, the target expression should select the containing object in the target document and update should contain an object with the property and its new primitive value.

Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced with a remove action followed by an update or copy action.

The properties of the update or copy object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the update object is merged with the target object by recursively applying these steps:

  • A property that only exists in the target object is left unchanged.
  • A property that only exists in the update or copy object is inserted into the target object.
  • If a property exists in both update or copy and target object:
    • A primitive value of the update or copy property replaces a primitive value of the target property.
    • An array value of the update or copy property is concatenated with an array value of the target property.
    • An object value of the update or copy property is recursively merged with an object value of the target property.
    • Other property value combinations are incompatible and result in an error.

This object MAY be extended with Specification Extensions.

Examples

Structured Overlay Example

When updating properties throughout the target document it may be more efficient to create a single Action Object that mirrors the structure of the target document. e.g.

overlay: 1.0.0
info:
  title: Structured Overlay
  version: 1.0.0
actions:
  - target: '$' # Root of document
    update:
      info:
        x-overlay-applied: structured-overlay
      paths:
        '/':
          summary: 'The root resource'
          get:
            summary: 'Retrieve the root resource'
            x-rate-limit: 100
        '/pets':
          get:
            summary: 'Retrieve a list of pets'
            x-rate-limit: 100
      components:
      tags:

Targeted Overlay Example

Alternatively, where only a small number of updates need to be applied to a large document, each Action Object MAY be more targeted.

overlay: 1.0.0
info:
  title: Targeted Overlay
  version: 1.0.0
actions:
  - target: $.paths['/foo'].get
    update:
      description: This is the new description
  - target: $.paths['/bar'].get
    update:
      description: This is the updated description
  - target: $.paths['/bar']
    update:
      post:
        description: This is an updated description of a child object
        x-safe: false

Wildcard Overlay Example

One significant advantage of using the JSONPath syntax is that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards and other multi-value selectors.

overlay: 1.0.0
info:
  title: Update many objects at once
  version: 1.0.0
actions:
  - target: $.paths.*.get
    update:
      x-safe: true
  - target: $.paths.*.get.parameters[?@.name=='filter' && @.in=='query']
    update:
      schema:
        $ref: '#/components/schemas/filterSchema'

Array Modification Examples

Array elements can be added using the update action.

overlay: 1.0.0
info:
  title: Add an array element
  version: 1.0.0
actions:
  - target: $.paths.*.get.parameters
    update:
      name: newParam
      in: query

Array elements can be deleted using the remove action. Use of array indexes to remove array items should be avoided where possible as indexes will change when items are removed.

overlay: 1.0.0
info:
  title: Remove an array element
  version: 1.0.0
actions:
  - target: $.paths.*.get.parameters[?@.name == 'dummy']
    remove: true

Traits Example

By annotating a target document (such as an [[OpenAPI]] document) using Specification Extensions such as x-oai-traits, the author of the target document MAY identify where overlay updates should be applied.

openapi: 3.1.0
info:
  title: API with a paged collection
  version: 1.0.0
paths:
  /items:
    get:
      x-oai-traits: ['paged']
      responses:
        200:
          description: OK
  /items/{id}/subitems:
    get:
      x-oai-traits: ['paged']
      parameters:
        - name: id
          in: path
          required: true
      responses:
        200:
          description: OK
  /other:
    get:
      responses:
        200:
          description: OK

With the above OpenAPI document, the following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied.

overlay: 1.0.0
info:
  title: Apply Traits
  version: 1.0.0
actions:
  - target: $.paths.*.get[?(@.x-oai-traits[?(@ == 'paged')])]
    update:
      parameters:
        - name: top
          in: query
          # ...
        - name: skip
          in: query
          # ...

resulting in

openapi: 3.1.0
info:
  title: API with a paged collection
  version: 1.0.0
paths:
  /items:
    get:
      x-oai-traits: ["paged"]
      responses:
        200:
          description: OK
      parameters:
        - name: top
          in: query
          # ...
        - name: skip
          in: query
          # ...
  /items/{id}/subitems:
    get:
      x-oai-traits: ["paged"]
      parameters:
        - name: id
          in: path
          required: true
        - name: top
          in: query
          # ...
        - name: skip
          in: query
          # ...
      responses:
        200:
          description: OK
  /other:
    get:
      responses:
        200:
          description: OK

This approach allows inversion of control as to where the Overlay updates apply to the target document itself.

Specification Extensions

While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extension properties are implemented as patterned fields that are always prefixed by "x-".

Field Pattern Type Description
^x- Any Allows extensions to the Overlay Specification. The field name MUST begin with x-, for example, x-internal-id. Field names beginning x-oai- and x-oas- are reserved for uses defined by the OpenAPI Initiative. The value MAY be null, a primitive, an array or an object.

The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).

File Naming Convention

Overlay files MAY choose to follow the convention of a purpose.overlay.yaml file naming pattern. Other file naming conventions are also supported.

RFC9535 compliance

[[RFC9535]] is a recent specification and libraries implementing JSONPath support might predate the RFC. Those libraries might differ entirely (expressions syntax is incompatible), or implement additional capabilities (superset of the RFC). A tool or library MUST fully implement [[RFC9535]] when parsing and expanding JSONPath query expressions to be compliant with the Overlay specification.

Interoperable Overlay Documents MUST use RFC9535 JSONPath query expressions and MUST NOT use tool-specific JSONPath extensions.

Comments in OpenAPI descriptions

Some formats, like YAML or JSONC, support using comments which do not impact the semantic meaning of the description. Applying Overlay Actions to a description MAY result in the loss of such comments in the updated description. The exact behavior is specific to the tool implementing the Overlay Specification.

Appendix A: Revision History

Version Date Notes
1.1.0 TBD Release of the Overlay Specification 1.1.0
1.0.0 2024-10-17 First release of the Overlay Specification