Skip to content

Commit 5535364

Browse files
baywetbaywet
authored
Merge pull request #150 from baywet/feat/copy-node
Adds a copy action
2 parents 3f6bab2 + 4e31667 commit 5535364

File tree

3 files changed

+208
-2
lines changed

3 files changed

+208
-2
lines changed

‎schemas/v1.1-dev/schema.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ $defs:
5151
- array
5252
- number
5353
- "null"
54+
copy:
55+
type: string
5456
remove:
5557
type: boolean
5658
default: false

‎tests/v1.1-dev/pass/copy-path-item-example.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
overlay: 1.1.0
2+
info:
3+
title: Merge an existing path item with another one
4+
version: 1.0.0
5+
actions:
6+
- target: '$.paths["/bar"]'
7+
copy: '$.paths["/foo"]'

‎versions/1.1.0-dev.md‎

Lines changed: 199 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The main purpose of the Overlay Specification is to provide a way to repeatably
2121

2222
### Overlay
2323

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|RFC9535 JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.
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`, `remove`, or `copy`). 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.
2525

2626
## Specification
2727

@@ -115,7 +115,8 @@ This object represents one or more changes to be applied to the target document
115115
| ---- | :----: | ---- |
116116
| <a name="action-target"></a>target | `string` | **REQUIRED** A RFC9535 JSONPath query expression selecting nodes in the target document. |
117117
| <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`. |
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` or if the `copy` field contains a value. |
119+
| <a name="action-copy"></a>copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. 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` or if the `update` field contains a value. |
119120
| <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`. |
120121

121122
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.
@@ -126,6 +127,8 @@ Primitive-valued items of an array cannot be replaced or removed individually, o
126127

127128
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.
128129

130+
The properties of the resolved `copy` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the resolved `copy` object are recursively merged with the properties in the target object with the same names; new properties are added to the target object.
131+
129132
This object MAY be extended with [Specification Extensions](#specification-extensions).
130133

131134
### Examples
@@ -267,6 +270,200 @@ actions:
267270

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

273+
#### Copy example
274+
275+
Copy actions behave similarly to `update` actions but source the new values to merge with the target from the document being transformed instead of providing them in the Overlay document. Copy actions MAY be used in sequence with `update` or `remove` actions to perform more advanced transformations like moving or renaming nodes.
276+
277+
##### Simple copy
278+
279+
This example shows how to copy all operations from the `items` path item to the `some-items` path item.
280+
281+
###### Source description
282+
283+
```yaml
284+
openapi: 3.1.0
285+
info:
286+
title: Example API
287+
version: 1.0.0
288+
paths:
289+
/items:
290+
get:
291+
responses:
292+
200:
293+
description: OK
294+
/some-items:
295+
delete:
296+
responses:
297+
200:
298+
description: OK
299+
```
300+
301+
###### Overlay
302+
303+
```yaml
304+
overlay: 1.1.0
305+
info:
306+
title: Copy contents of an existing path to a new location
307+
version: 1.0.0
308+
actions:
309+
- target: '$.paths["/some-items"]'
310+
copy: '$.paths["/items"]'
311+
description: 'copies recursively all elements from the "items" path item to the new "some-items" path item without ensuring the node exists before the copy'
312+
```
313+
314+
###### Result description
315+
316+
```yaml
317+
openapi: 3.1.0
318+
info:
319+
title: Example API
320+
version: 1.0.0
321+
paths:
322+
/items:
323+
get:
324+
responses:
325+
200:
326+
description: OK
327+
/some-items:
328+
get:
329+
responses:
330+
200:
331+
description: OK
332+
delete:
333+
responses:
334+
200:
335+
description: OK
336+
```
337+
338+
##### Ensure the target exists and copy
339+
340+
This example shows how to copy all operations from the `items` path item to the `other-items` path item after first ensuring the target exists with an update action.
341+
342+
###### Source description
343+
344+
```yaml
345+
openapi: 3.1.0
346+
info:
347+
title: Example API
348+
version: 1.0.0
349+
paths:
350+
/items:
351+
get:
352+
responses:
353+
200:
354+
description: OK
355+
/some-items:
356+
delete:
357+
responses:
358+
200:
359+
description: OK
360+
```
361+
362+
###### Overlay
363+
364+
```yaml
365+
overlay: 1.1.0
366+
info:
367+
title: Create a path and copy the contents of an existing path to the new path
368+
version: 1.0.0
369+
actions:
370+
- target: '$.paths'
371+
update: { "/other-items": {} }
372+
- target: '$.paths["/other-items"]'
373+
copy: '$.paths["/items"]'
374+
description: 'copies recursively all elements from the "items" path item to the new "other-items" path item while ensuring the node exists before the copy'
375+
```
376+
377+
###### Result description
378+
379+
```yaml
380+
openapi: 3.1.0
381+
info:
382+
title: Example API
383+
version: 1.0.0
384+
paths:
385+
/items:
386+
get:
387+
responses:
388+
200:
389+
description: OK
390+
/other-items:
391+
get:
392+
responses:
393+
200:
394+
description: OK
395+
/some-items:
396+
delete:
397+
responses:
398+
200:
399+
description: OK
400+
```
401+
402+
##### Move example
403+
404+
This example shows how to rename the `items` path item to `new-items` using a sequence of overlay actions:
405+
406+
1. Use an `update` action to ensure the target path item exists.
407+
2. Use a `copy` action to copy the source path item to the target.
408+
3. Use a `remove` action to delete the original source path item.
409+
410+
###### Source description
411+
412+
```yaml
413+
openapi: 3.1.0
414+
info:
415+
title: Example API
416+
version: 1.0.0
417+
paths:
418+
/items:
419+
get:
420+
responses:
421+
200:
422+
description: OK
423+
/some-items:
424+
delete:
425+
responses:
426+
200:
427+
description: OK
428+
```
429+
430+
###### Overlay
431+
432+
```yaml
433+
overlay: 1.1.0
434+
info:
435+
title: Update the path for an API endpoint
436+
version: 1.0.0
437+
actions:
438+
- target: '$.paths'
439+
update: { "/new-items": {} }
440+
- target: '$.paths["/new-items"]'
441+
copy: '$.paths["/items"]'
442+
- target: '$.paths["/items"]'
443+
remove: true
444+
description: 'moves (renames) the "items" path item to "new-items"'
445+
```
446+
447+
###### Result description
448+
449+
```yaml
450+
openapi: 3.1.0
451+
info:
452+
title: Example API
453+
version: 1.0.0
454+
paths:
455+
/new-items:
456+
get:
457+
responses:
458+
200:
459+
description: OK
460+
/some-items:
461+
delete:
462+
responses:
463+
200:
464+
description: OK
465+
```
466+
270467
### Specification Extensions
271468

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

0 commit comments

Comments
 (0)