Overlay Specification v1.0.0

TBD

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

Overlay Specification

Version 1.0.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

TBD

Definitions

Overlay Document

An overlay document contains an ordered list of Update Objects that are to be applied to the target document. Each Update Object has a target property and a modifier type (add, merge, remove). The target property is a JMESPath query that identifies what part of the target document is to be updated and the modifier determines the change.

Specification

Versions

TBD

Format

An Overlay document that conforms to the Overlay Specification is itself a JSON object, which may be represented either in JSON or 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 version 1.2 is RECOMMENDED along with some additional constraints:

Document Structure

It is RECOMMENDED that the root Overlay document be named: TBD.

Data Types

TBD

Relative References in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [[!RFC3986]]. *** Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.

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 document.

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 URL to an OpenAPI document this overlay applies to. This MUST be in the form of a URL.
updates [Update Object] REQUIRED An ordered list of update objects 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 update objects MUST be applied in sequential order to ensure a consistent outcome. Updates are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update, for example.

The extends property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. Where no extends is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description.

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 identifer for indicating changes to the Overlay document.

*** This object MAY be extended with Specification Extensions.

Update Object

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

Fixed Fields

Field Name Type Description
target string REQUIRED A JMESPath expression referencing the target objects in the target document.
add Any An object to be added as a child of the object(s) referenced by the target. Property has no impact if remove property is true.
merge Any An object with the properties and values to be merged with the object(s) referenced by the target. Property has no impact if remove property is true.
remove boolean A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false.

The properties of the merge object MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object.

*** This object MAY be extended with Specification Extensions.

Examples

Structured Overlays Example

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


overlay: 1.0.0
info:
  title: Structured Overlay
  version: 1.0.0
updates:
- target: "@"
  merge:
    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 Overlays

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


overlay: 1.0.0
info:
  title: Targeted Overlays
  version: 1.0.0
updates:
- target: paths."/foo".get
  merge:
    description: This is the new description
- target: paths."/bar".get
  merge:
    description: This is the updated description
- target: paths."/bar"
  merge:
      post:
          description: This is an updated description of a child object
          x-safe: false

Wildcard Overlays Examples

One significant advantage of using the JMESPath syntax 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.


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

Array Modification Examples

Due to the fact that we can now reference specific elements of the parameter array, it allows adding parameters. Parameters can be deleted using the remove property. Use of indexes to remove array items should be avoided where possible as indexes will change when items are removed.


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


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

Traits Examples

By annotating an OpenAPI description using extension such as x-oai-traits an author of OpenAPI description can 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

With the above OpenAPI description, 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
updates:
- target: $.paths[*].get[?contains(x-traits,'paged')]
  merge:
    parameters:
      - name: top
        in: query
      - name: skip
        in: query

This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself.

Specification Extensions

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

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

Field Pattern Type Description
^x- Any Allows extensions to the OpenAPI Schema. 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 can 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).

Appendix A: Revision History

Version Date Notes
1.0.0 TBD First release of the Overlay Specification