Skip to content

Commit c37db72

Browse files
lornajanelornajane
committed
Copy 1.0.0 to working spec file location for ongoing development
1 parent 0dadb48 commit c37db72

File tree

1 file changed

+284
-0
lines changed

1 file changed

+284
-0
lines changed

‎spec/overlay.md

+284
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
# Overlay Specification
2+
3+
## Abstract
4+
5+
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).
6+
7+
## Version 1.0.0
8+
9+
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](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
10+
11+
This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
12+
13+
## Introduction
14+
15+
The Overlay Specification is a companion to the [[OpenAPI]] Specification.
16+
An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description.
17+
18+
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.
19+
20+
## Definitions
21+
22+
### Overlay
23+
24+
An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlay-actions) that are to be applied to the target document. Each [Action Object](#action-object) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [[RFC9535|JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.
25+
26+
## Specification
27+
28+
### Versions
29+
30+
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.
31+
32+
**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.
33+
34+
### Format
35+
36+
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.
37+
38+
All field names in the specification are **case sensitive**.
39+
This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
40+
41+
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:
42+
43+
- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).
44+
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).
45+
46+
### Relative References in URIs
47+
48+
Unless specified otherwise, all fields that are URI references MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
49+
50+
### Schema
51+
52+
In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
53+
54+
#### Overlay Object
55+
56+
This is the root object of the [Overlay](#overlay).
57+
58+
##### Fixed Fields
59+
60+
| Field Name | Type | Description |
61+
| ---- | :----: | ---- |
62+
| <a name="overlay-version"></a>overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. |
63+
| <a name="overlay-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. |
64+
| <a name="overlay-extends"></a>extends | `string` | URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to. |
65+
| <a name="overlay-actions"></a>actions | [[Action Object](#action-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
66+
67+
This object MAY be extended with [Specification Extensions](#specification-extensions).
68+
69+
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.
70+
71+
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).
72+
73+
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.
74+
75+
```yaml
76+
overlay: 1.0.0
77+
info:
78+
title: Overlay for the Tic Tac Toe API document
79+
version: 1.0.0
80+
extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
81+
...
82+
```
83+
84+
The `extends` property can also specify a relative URI reference.
85+
86+
```yaml
87+
overlay: 1.0.0
88+
info:
89+
title: Overlay for the Tic Tac Toe API document
90+
version: 1.0.0
91+
extends: './tictactoe.yaml'
92+
```
93+
94+
#### Info Object
95+
96+
The object provides metadata about the Overlay.
97+
The metadata MAY be used by the clients if needed.
98+
99+
##### Fixed Fields
100+
101+
| Field Name | Type | Description |
102+
| ---- | :----: | ---- |
103+
| <a name="info-title"></a>title | `string` | **REQUIRED**. A human readable description of the purpose of the overlay. |
104+
| <a name="info-version"></a>version | `string` | **REQUIRED**. A version identifer for indicating changes to the Overlay document. |
105+
106+
This object MAY be extended with [Specification Extensions](#specification-extensions).
107+
108+
#### Action Object
109+
110+
This object represents one or more changes to be applied to the target document at the location defined by the target JSONPath expression.
111+
112+
##### Fixed Fields
113+
114+
| Field Name | Type | Description |
115+
| ---- | :----: | ---- |
116+
| <a name="action-target"></a>target | `string` | **REQUIRED** A JSONPath expression selecting nodes in the target document. |
117+
| <a name="action-description"></a>description | `string` | A description of the action. [[CommonMark]] syntax MAY be used for rich text representation. |
118+
| <a name="action-update"></a>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`. |
119+
| <a name="action-remove"></a>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`. |
120+
121+
The result of the `target` JSONPath expression MUST be zero or more objects or arrays (not primitive types or `null` values).
122+
123+
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.
124+
125+
Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced.
126+
127+
The properties of the `update` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the `update` object are recursively merged with the properties in the target object with the same names; new properties are added to the target object.
128+
129+
This object MAY be extended with [Specification Extensions](#specification-extensions).
130+
131+
### Examples
132+
133+
#### Structured Overlay Example
134+
135+
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.
136+
137+
```yaml
138+
overlay: 1.0.0
139+
info:
140+
title: Structured Overlay
141+
version: 1.0.0
142+
actions:
143+
- target: '$' # Root of document
144+
update:
145+
info:
146+
x-overlay-applied: structured-overlay
147+
paths:
148+
'/':
149+
summary: 'The root resource'
150+
get:
151+
summary: 'Retrieve the root resource'
152+
x-rate-limit: 100
153+
'/pets':
154+
get:
155+
summary: 'Retrieve a list of pets'
156+
x-rate-limit: 100
157+
components:
158+
tags:
159+
```
160+
161+
#### Targeted Overlay Example
162+
163+
Alternatively, where only a small number of updates need to be applied to a large document, each [Action Object](#action-object) MAY be more targeted.
164+
165+
```yaml
166+
overlay: 1.0.0
167+
info:
168+
title: Targeted Overlay
169+
version: 1.0.0
170+
actions:
171+
- target: $.paths['/foo'].get
172+
update:
173+
description: This is the new description
174+
- target: $.paths['/bar'].get
175+
update:
176+
description: This is the updated description
177+
- target: $.paths['/bar']
178+
update:
179+
post:
180+
description: This is an updated description of a child object
181+
x-safe: false
182+
```
183+
184+
#### Wildcard Overlay Example
185+
186+
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.
187+
188+
```yaml
189+
overlay: 1.0.0
190+
info:
191+
title: Update many objects at once
192+
version: 1.0.0
193+
actions:
194+
- target: $.paths.*.get
195+
update:
196+
x-safe: true
197+
- target: $.paths.*.get.parameters[[email protected]=='filter' && @.in=='query']
198+
update:
199+
schema:
200+
$ref: '/components/schemas/filterSchema'
201+
```
202+
203+
#### Array Modification Example
204+
205+
Array elements MAY be deleted using the `remove` property. Use of array indexes to remove array items should be avoided where possible as indexes will change when items are removed.
206+
207+
```yaml
208+
overlay: 1.0.0
209+
info:
210+
title: Add an array element
211+
version: 1.0.0
212+
actions:
213+
- target: $.paths.*.get.parameters
214+
update:
215+
name: newParam
216+
in: query
217+
```
218+
219+
```yaml
220+
overlay: 1.0.0
221+
info:
222+
title: Remove a array element
223+
version: 1.0.0
224+
actions:
225+
- target: $.paths.*.get.parameters[[email protected] == 'dummy']
226+
remove: true
227+
```
228+
229+
#### Traits Example
230+
231+
By annotating a target document (such as an [[OpenAPI]] document) using [Specification Extensions](#specification-extensions) such as `x-oai-traits`, the author of the target document MAY identify where overlay updates should be applied.
232+
233+
```yaml
234+
openapi: 3.1.0
235+
info:
236+
title: API with a paged collection
237+
version: 1.0.0
238+
paths:
239+
/items:
240+
get:
241+
x-oai-traits: ['paged']
242+
responses:
243+
200:
244+
description: OK
245+
```
246+
247+
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.
248+
249+
```yaml
250+
overlay: 1.0.0
251+
info:
252+
title: Apply Traits
253+
version: 1.0.0
254+
actions:
255+
- target: $.paths.*.get[[email protected]]
256+
update:
257+
parameters:
258+
- name: top
259+
in: query
260+
# ...
261+
- name: skip
262+
in: query
263+
# ...
264+
```
265+
266+
This approach allows inversion of control as to where the Overlay updates apply to the target document itself.
267+
268+
### Specification Extensions
269+
270+
While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
271+
272+
The extension properties are implemented as patterned fields that are always prefixed by `"x-"`.
273+
274+
| Field Pattern | Type | Description |
275+
| ---- | :--: | ---- |
276+
| <a name="overlay-extensions"></a>^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](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. |
277+
278+
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).
279+
280+
## Appendix A: Revision History
281+
282+
| Version | Date | Notes |
283+
| ---- | ---- | ---- |
284+
| 1.0.0 | 2024-10-17 | First release of the Overlay Specification |

0 commit comments

Comments
 (0)