Skip to content

Commit 4eee801

Browse files
darrelmillerdarrelmiller
authored
Overlay proposal (#1864)
* Moved contents of overlay issue to a proposal document * Added overlay proposal * Updates based on feedback plus some scenarios
1 parent 87bbda6 commit 4eee801

File tree

1 file changed

+194
-0
lines changed

1 file changed

+194
-0
lines changed

‎proposals/004_Overlays.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Overlays
2+
3+
## Metadata
4+
5+
|Tag |Value |
6+
|---- | ---------------- |
7+
|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)|
8+
|Authors|[Darrel Miller](https://github.com/darrelmiller)|
9+
|Status |Proposal|
10+
|Issues |[1442](https://github.com/OAI/OpenAPI-Specification/issues/1442) [1722](https://github.com/OAI/OpenAPI-Specification/issues/1722)|
11+
12+
## Change Log
13+
14+
|Date |Responsible Party |Description |
15+
|---- | ---------------- | ---------- |
16+
| 24th December 2019 | Darrel Miller | Initial draft |
17+
| 2nd January 2019 | Darrel Miller | Update to wording around removing items from arrays. Added section on backward compatibility. Clarified process around applying a set of updates. Started to add supported scenarios.|
18+
19+
## Introduction
20+
21+
In recent months we have been discussing various use cases for overlays and various solutions. The following proposal takes a somewhat more radical approach to the problem. It is a more ambitious proposal than the others we have seen before but the additional complexity does allow for supporting many of the scenarios that have been discussed to date.
22+
23+
24+
#### <a name="overlayDocument"></a>Overlay Document
25+
26+
An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid.
27+
28+
29+
#### <a name="overlayObject"></a>Overlay Object
30+
31+
This is the root object of the [OpenAPI Overlay document](#oasDocument).
32+
33+
##### Fixed Fields
34+
35+
Field Name | Type | Description
36+
---|:---:|---
37+
<a name="overlayVersion"></a>overlay | `string` | Version of the Overlay specification that this document conforms to.
38+
<a name="overlayInfo"></a>info | [[Info Object](#overlayInfoObject)] | Identifying information about the overlay.
39+
<a name="overlayExtends"></a>extends | `url` | URL to an OpenAPI document this overlay applies to.
40+
<a name="overlayUpdates"></a>updates | [[Update Object](#updateObject)] | A list of update objects to be applied to the target document.
41+
42+
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.
43+
44+
The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. This is an optional property. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description.
45+
46+
#### <a name="overlayInfoObject"></a>Info Object
47+
48+
This object contains identifying information about the [OpenAPI Overlay document](#oasDocument).
49+
50+
##### Fixed Fields
51+
52+
Field Name | Type | Description
53+
---|:---:|---
54+
<a name="overlayTitle"></a>title | `string` | A human readable description of the purpose of the overlay.
55+
<a name="overlayVersion"></a>version | `string` | A version identifer for indicating changes to an overlay document.
56+
57+
#### <a name="updateObject"></a>Update Object
58+
59+
This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath.
60+
61+
##### Fixed Fields
62+
63+
Field Name | Type | Description
64+
---|:---:|---
65+
<a name="updateTarget"></a>target | `string` | A JMESPath expression referencing the target objects in the target document.
66+
<a name="updateValue"></a>value | [Any](#valueObject) | An object with the properties and values to be updated in the target document. Property has no impact if `remove` property is `true`.
67+
<a name="updateRemove"></a>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.
68+
69+
The properties of the `Value Object` MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the `Value Object` replace properties in the target object with the same name and new properties are appended to the target object.
70+
71+
##### Structured Overlays Example
72+
73+
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.
74+
75+
```yaml
76+
overlay: 1.0.0
77+
info:
78+
title: Structured Overlay
79+
version: 1.0.0
80+
updates:
81+
- target: "@"
82+
value:
83+
info:
84+
x-overlay-applied: structured-overlay
85+
paths:
86+
"/":
87+
summary: "The root resource"
88+
get:
89+
summary: "Retrieve the root resource"
90+
x-rate-limit: 100
91+
"/pets":
92+
get:
93+
summary: "Retrieve a list of pets"
94+
x-rate-limit: 100
95+
components:
96+
tags:
97+
```
98+
99+
##### Targeted Overlays
100+
101+
Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) can be more targeted.
102+
103+
```yaml
104+
overlay: 1.0.0
105+
info:
106+
title: Structured Overlay
107+
version: 1.0.0
108+
updates:
109+
- target: paths."/foo".get
110+
value:
111+
description: This is the new description
112+
- target: paths."/bar".get
113+
value:
114+
description: This is the updated description
115+
- target: paths."/bar"
116+
value:
117+
post:
118+
description: This is an updated description of a child object
119+
x-safe: false
120+
```
121+
122+
##### Wildcard Overlays Examples
123+
124+
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.
125+
126+
```yaml
127+
overlay: 1.0.0
128+
info:
129+
title: Update many objects at once
130+
version: 1.0.0
131+
updates:
132+
- target: paths.*.get
133+
value:
134+
x-safe: true
135+
- target: paths.*.get.parameters[?name=='filter' && in=='query']
136+
value:
137+
schema:
138+
$ref: "/components/schemas/filterSchema"
139+
```
140+
141+
##### Array Modification Examples
142+
143+
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.
144+
145+
```yaml
146+
overlay: 1.0.0
147+
info:
148+
title: Add an array element
149+
version: 1.0.0
150+
updates:
151+
- target: paths.*.get.parameters[length(@)]
152+
value:
153+
name: newParam
154+
in: query
155+
```
156+
157+
```yaml
158+
overlay: 1.0.0
159+
info:
160+
title: Remove a array element
161+
version: 1.0.0
162+
updates:
163+
- target: $.paths[*].get.parameters[? name == 'dummy']
164+
remove: true
165+
```
166+
167+
## Proposal Summary
168+
169+
### Benefits
170+
171+
- This approach addresses the two distinct approaches of structured overlay vs targeted overlay which suits distinct but equally valid scenarios.
172+
- Addresses the problem of modifying the parameters array and removes the need to replace the entire array when a small change is required.
173+
- Allows sets of related overlays to be stored in a same file.
174+
- Enables updating a set of objects based on a pattern. This might be an effective way of apply common behaviour across many operations in an API.
175+
176+
### Challenges
177+
178+
- Tooling will need a JMESPath implementation.
179+
- Large overlays may be slow to process.
180+
- Multiple complex pattern based overlays may cause overlapping updates causing confusing outcomes.
181+
182+
## Alternatives considered
183+
184+
JMESPath was chosen over JSONPath due to the fact that JMESPath has a [specification](http://jmespath.org/specification.html) and a set of test cases. This will help to ensure compatibility between implementations.
185+
186+
## Backwards compatibility
187+
188+
Overlays will be described in a new specification that can be used alongside an OpenAPI Description, therefore there will be no compatibility issues for the initial release. Overlay documents can be used against OpenAPI v2 and v3 descriptions.
189+
190+
## Scenarios Considered
191+
192+
- Multi-language support. An Overlay document for each language is used to target a specific OpenAPI description. The Overlay document will likely use a duplicate structure to the original OpenAPI description and replace all `description` properties.
193+
- Applying API wide standards. An Overlay document contains update objects that describe standard headers, parameters, responses. These documents would use JMESPath queries to target the appropriate objects in the OpenAPI description. Tooling could be used to target the OpenAPI description rather than using extends.
194+
- Add tool specific OpenAPI metadata. Overlay adds additional metadata such as SLA information, client codegen hints or middleware policies. Using Overlays to manage this data separately is valuable when there is a different audience for the data and/or there the information has different sensitivity levels.

0 commit comments

Comments
 (0)