diff --git a/schemas/v1.2-dev/schema.yaml b/schemas/v1.2-dev/schema.yaml
index 4891415..292d8fb 100644
--- a/schemas/v1.2-dev/schema.yaml
+++ b/schemas/v1.2-dev/schema.yaml
@@ -16,7 +16,11 @@ properties:
minItems: 1
uniqueItems: true
items:
- $ref: "#/$defs/action-object"
+ oneOf:
+ - $ref: "#/$defs/reusable-action-reference-object"
+ - $ref: "#/$defs/action-object"
+ components:
+ $ref: "#/$defs/components-object"
required:
- overlay
- info
@@ -24,6 +28,45 @@ required:
$ref: "#/$defs/specification-extensions"
unevaluatedProperties: false
$defs:
+ reusable-action-reference-object:
+ type: object
+ allOf:
+ - $ref: "#/$defs/specification-extensions"
+ - $ref: "#/$defs/description-field"
+ - $ref: "#/$defs/target-field"
+ properties:
+ $ref:
+ type: string
+ pattern: ^#\/components\/actions\/(?:[^~/]|~0|~1)+$
+ required:
+ - $ref
+ - target
+ unevaluatedProperties: false
+ reusable-action-fields-object:
+ type: object
+ allOf:
+ - $ref: "#/$defs/description-field"
+ - $ref: "#/$defs/action-fields"
+ - $ref: "#/$defs/specification-extensions"
+ unevaluatedProperties: false
+ reusable-action-object:
+ type: object
+ allOf:
+ - $ref: "#/$defs/specification-extensions"
+ - $ref: "#/$defs/description-field"
+ properties:
+ fields:
+ $ref: "#/$defs/reusable-action-fields-object"
+ unevaluatedProperties: false
+ components-object:
+ type: object
+ properties:
+ actions:
+ type: object
+ additionalProperties:
+ $ref: "#/$defs/reusable-action-object"
+ $ref: "#/$defs/specification-extensions"
+ unevaluatedProperties: false
info-object:
type: object
properties:
@@ -31,21 +74,27 @@ $defs:
type: string
version:
type: string
- description:
- type: string
+ allOf:
+ - $ref: "#/$defs/description-field"
required:
- title
- version
$ref: "#/$defs/specification-extensions"
unevaluatedProperties: false
- action-object:
+ description-field:
+ type: object
+ properties:
+ description:
+ type: string
+ target-field:
type: object
properties:
target:
type: string
pattern: ^\$
- description:
- type: string
+ action-fields:
+ type: object
+ properties:
update:
type:
- string
@@ -59,9 +108,15 @@ $defs:
remove:
type: boolean
default: false
+ action-object:
+ type: object
+ allOf:
+ - $ref: "#/$defs/description-field"
+ - $ref: "#/$defs/target-field"
+ - $ref: "#/$defs/action-fields"
+ - $ref: "#/$defs/specification-extensions"
required:
- target
- $ref: "#/$defs/specification-extensions"
unevaluatedProperties: false
specification-extensions:
patternProperties:
diff --git a/tests/v1.2-dev/fail/components-actions-invalid-type.yaml b/tests/v1.2-dev/fail/components-actions-invalid-type.yaml
new file mode 100644
index 0000000..a63ac20
--- /dev/null
+++ b/tests/v1.2-dev/fail/components-actions-invalid-type.yaml
@@ -0,0 +1,8 @@
+overlay: 1.2.0
+info:
+ title: Components actions must be an object
+ version: 1.0.0
+components:
+ actions: []
+actions:
+ - target: '$'
\ No newline at end of file
diff --git a/tests/v1.2-dev/fail/components-invalid-property.yaml b/tests/v1.2-dev/fail/components-invalid-property.yaml
new file mode 100644
index 0000000..5e3c27c
--- /dev/null
+++ b/tests/v1.2-dev/fail/components-invalid-property.yaml
@@ -0,0 +1,13 @@
+overlay: 1.2.0
+info:
+ title: Components invalid property
+ version: 1.0.0
+components:
+ invalidProperty: true
+ actions:
+ setDescription:
+ target: '$.info'
+ update:
+ description: Updated
+actions:
+ - target: '$.info'
diff --git a/tests/v1.2-dev/fail/components-invalid-type.yaml b/tests/v1.2-dev/fail/components-invalid-type.yaml
new file mode 100644
index 0000000..72665a4
--- /dev/null
+++ b/tests/v1.2-dev/fail/components-invalid-type.yaml
@@ -0,0 +1,7 @@
+overlay: 1.2.0
+info:
+ title: Components must be an object
+ version: 1.0.0
+components: []
+actions:
+ - target: '$'
diff --git a/tests/v1.2-dev/fail/components-reusable-action-invalid-type.yaml b/tests/v1.2-dev/fail/components-reusable-action-invalid-type.yaml
new file mode 100644
index 0000000..b84e519
--- /dev/null
+++ b/tests/v1.2-dev/fail/components-reusable-action-invalid-type.yaml
@@ -0,0 +1,9 @@
+overlay: 1.2.0
+info:
+ title: Components action must be an object
+ version: 1.0.0
+components:
+ actions:
+ brokenAction: not-an-object
+actions:
+ - target: '$'
diff --git a/tests/v1.2-dev/fail/reusable-action-description-invalid-type.yaml b/tests/v1.2-dev/fail/reusable-action-description-invalid-type.yaml
new file mode 100644
index 0000000..14fcd59
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-description-invalid-type.yaml
@@ -0,0 +1,14 @@
+overlay: 1.2.0
+info:
+ title: Reusable action with invalid description type
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ description: 42
+ fields:
+ update:
+ description: Updated by reusable action
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
diff --git a/tests/v1.2-dev/fail/reusable-action-fields-invalid-property.yaml b/tests/v1.2-dev/fail/reusable-action-fields-invalid-property.yaml
new file mode 100644
index 0000000..b6f7861
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-fields-invalid-property.yaml
@@ -0,0 +1,13 @@
+overlay: 1.2.0
+info:
+ title: Reusable action fields must not contain invalid properties
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields:
+ invalidProperty: true
+ update:
+ description: Updated
+actions:
+ - target: '$'
diff --git a/tests/v1.2-dev/fail/reusable-action-fields-invalid-type.yaml b/tests/v1.2-dev/fail/reusable-action-fields-invalid-type.yaml
new file mode 100644
index 0000000..93ef141
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-fields-invalid-type.yaml
@@ -0,0 +1,10 @@
+overlay: 1.2.0
+info:
+ title: Reusable action fields must be an object
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields: not-an-object
+actions:
+ - target: '$'
diff --git a/tests/v1.2-dev/fail/reusable-action-fields-target-not-allowed.yaml b/tests/v1.2-dev/fail/reusable-action-fields-target-not-allowed.yaml
new file mode 100644
index 0000000..e0ec4a6
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-fields-target-not-allowed.yaml
@@ -0,0 +1,14 @@
+overlay: 1.2.0
+info:
+ title: Reusable action fields with target not allowed
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields:
+ target: '$.info'
+ update:
+ description: Updated by reusable action
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
diff --git a/tests/v1.2-dev/fail/reusable-action-invalid-property.yaml b/tests/v1.2-dev/fail/reusable-action-invalid-property.yaml
new file mode 100644
index 0000000..99a0095
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-invalid-property.yaml
@@ -0,0 +1,13 @@
+overlay: 1.2.0
+info:
+ title: Reusable action invalid property
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields:
+ update:
+ description: Updated
+ invalidProperty: true
+actions:
+ - target: '$.info'
diff --git a/tests/v1.2-dev/fail/reusable-action-peer-action-fields.yaml b/tests/v1.2-dev/fail/reusable-action-peer-action-fields.yaml
new file mode 100644
index 0000000..ca9d595
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-peer-action-fields.yaml
@@ -0,0 +1,12 @@
+overlay: 1.2.0
+info:
+ title: Reusable action must not have action fields as peer properties
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ target: '$.info'
+ update:
+ description: Updated
+actions:
+ - target: '$'
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-copy-not-allowed.yaml b/tests/v1.2-dev/fail/reusable-action-reference-copy-not-allowed.yaml
new file mode 100644
index 0000000..71d64ad
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-copy-not-allowed.yaml
@@ -0,0 +1,13 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference must not contain copy
+ version: 1.0.0
+components:
+ actions:
+ copyInfoTitle:
+ fields:
+ copy: '$.info.title'
+actions:
+ - $ref: '#/components/actions/copyInfoTitle'
+ target: '$.info.summary'
+ copy: '$.info.description'
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-invalid-ref-type.yaml b/tests/v1.2-dev/fail/reusable-action-reference-invalid-ref-type.yaml
new file mode 100644
index 0000000..9c95a46
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-invalid-ref-type.yaml
@@ -0,0 +1,7 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference ref must be a string
+ version: 1.0.0
+actions:
+ - $ref: 100
+ target: '$'
\ No newline at end of file
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-invalid-ref.yaml b/tests/v1.2-dev/fail/reusable-action-reference-invalid-ref.yaml
new file mode 100644
index 0000000..da9c2aa
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-invalid-ref.yaml
@@ -0,0 +1,7 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference must point to components actions
+ version: 1.0.0
+actions:
+ - $ref: '#/components/notActions/errorResponse'
+ target: '$.info'
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-missing-target.yaml b/tests/v1.2-dev/fail/reusable-action-reference-missing-target.yaml
new file mode 100644
index 0000000..48591a3
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-missing-target.yaml
@@ -0,0 +1,12 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference missing required target
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields:
+ update:
+ description: Updated by reusable action
+actions:
+ - $ref: '#/components/actions/setDescription'
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-remove-not-allowed.yaml b/tests/v1.2-dev/fail/reusable-action-reference-remove-not-allowed.yaml
new file mode 100644
index 0000000..aeda48d
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-remove-not-allowed.yaml
@@ -0,0 +1,13 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference must not contain remove
+ version: 1.0.0
+components:
+ actions:
+ removeInfoDescription:
+ fields:
+ remove: true
+actions:
+ - $ref: '#/components/actions/removeInfoDescription'
+ target: '$.info.description'
+ remove: true
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-unescaped-component-key.yaml b/tests/v1.2-dev/fail/reusable-action-reference-unescaped-component-key.yaml
new file mode 100644
index 0000000..244e363
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-unescaped-component-key.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference with unescaped component key is invalid
+ version: 1.0.0
+components:
+ actions:
+ 'error-response/v1~beta':
+ fields:
+ description: Adds an error response
+ update:
+ '404':
+ description: Not Found
+actions:
+ - $ref: '#/components/actions/error-response/v1~beta'
+ target: '$.paths.*.get.responses'
\ No newline at end of file
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-unescaped-tilde-component-key.yaml b/tests/v1.2-dev/fail/reusable-action-reference-unescaped-tilde-component-key.yaml
new file mode 100644
index 0000000..4f052e4
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-unescaped-tilde-component-key.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference with unescaped tilde in component key is invalid
+ version: 1.0.0
+components:
+ actions:
+ 'error~response':
+ fields:
+ description: Adds an error response
+ update:
+ '404':
+ description: Not Found
+actions:
+ - $ref: '#/components/actions/error~response'
+ target: '$.paths.*.get.responses'
diff --git a/tests/v1.2-dev/fail/reusable-action-reference-update-not-allowed.yaml b/tests/v1.2-dev/fail/reusable-action-reference-update-not-allowed.yaml
new file mode 100644
index 0000000..8d51ddf
--- /dev/null
+++ b/tests/v1.2-dev/fail/reusable-action-reference-update-not-allowed.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference must not contain update
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields:
+ update:
+ description: Updated by reusable action
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
+ update:
+ description: Updated by reference
diff --git a/tests/v1.2-dev/pass/components-extensions.yaml b/tests/v1.2-dev/pass/components-extensions.yaml
new file mode 100644
index 0000000..1297f9d
--- /dev/null
+++ b/tests/v1.2-dev/pass/components-extensions.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Components extensions
+ version: 1.0.0
+components:
+ x-components-extension:
+ enabled: true
+ actions:
+ setDescription:
+ fields:
+ update:
+ description: Updated
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
diff --git a/tests/v1.2-dev/pass/components-reusable-actions.yaml b/tests/v1.2-dev/pass/components-reusable-actions.yaml
new file mode 100644
index 0000000..e8cbf6c
--- /dev/null
+++ b/tests/v1.2-dev/pass/components-reusable-actions.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Components with reusable actions
+ version: 1.0.0
+components:
+ actions:
+ errorResponse:
+ fields:
+ description: Adds an error response
+ update:
+ '404':
+ description: Not Found
+actions:
+ - $ref: '#/components/actions/errorResponse'
+ target: '$.paths.*.get.responses'
diff --git a/tests/v1.2-dev/pass/reusable-action-description.yaml b/tests/v1.2-dev/pass/reusable-action-description.yaml
new file mode 100644
index 0000000..46d470b
--- /dev/null
+++ b/tests/v1.2-dev/pass/reusable-action-description.yaml
@@ -0,0 +1,14 @@
+overlay: 1.2.0
+info:
+ title: Reusable action with description
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ description: A reusable action that updates the info description
+ fields:
+ update:
+ description: Updated by reusable action
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
diff --git a/tests/v1.2-dev/pass/reusable-action-empty-fields.yaml b/tests/v1.2-dev/pass/reusable-action-empty-fields.yaml
new file mode 100644
index 0000000..b6a3f5c
--- /dev/null
+++ b/tests/v1.2-dev/pass/reusable-action-empty-fields.yaml
@@ -0,0 +1,11 @@
+overlay: 1.2.0
+info:
+ title: Reusable action with empty fields
+ version: 1.0.0
+components:
+ actions:
+ placeholder:
+ description: This does not do anything because of the empty fields and lack of reference, it's just to validate a schema permutation.
+ fields: {}
+actions:
+ - target: '$'
diff --git a/tests/v1.2-dev/pass/reusable-action-extensions.yaml b/tests/v1.2-dev/pass/reusable-action-extensions.yaml
new file mode 100644
index 0000000..2c7b2cf
--- /dev/null
+++ b/tests/v1.2-dev/pass/reusable-action-extensions.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Reusable action extensions
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ x-action-extension:
+ mode: reusable
+ fields:
+ update:
+ description: Updated
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
diff --git a/tests/v1.2-dev/pass/reusable-action-reference-escaped-component-key.yaml b/tests/v1.2-dev/pass/reusable-action-reference-escaped-component-key.yaml
new file mode 100644
index 0000000..06b2c84
--- /dev/null
+++ b/tests/v1.2-dev/pass/reusable-action-reference-escaped-component-key.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference with escaped component key
+ version: 1.0.0
+components:
+ actions:
+ 'error-response/v1~beta':
+ fields:
+ description: Adds an error response
+ update:
+ '404':
+ description: Not Found
+actions:
+ - $ref: '#/components/actions/error-response~1v1~0beta'
+ target: '$.paths.*.get.responses'
\ No newline at end of file
diff --git a/tests/v1.2-dev/pass/reusable-action-reference-extensions.yaml b/tests/v1.2-dev/pass/reusable-action-reference-extensions.yaml
new file mode 100644
index 0000000..d0a5281
--- /dev/null
+++ b/tests/v1.2-dev/pass/reusable-action-reference-extensions.yaml
@@ -0,0 +1,15 @@
+overlay: 1.2.0
+info:
+ title: Reusable action reference extensions
+ version: 1.0.0
+components:
+ actions:
+ setDescription:
+ fields:
+ update:
+ description: Updated
+actions:
+ - $ref: '#/components/actions/setDescription'
+ target: '$.info'
+ x-reference-extension:
+ applied: true
diff --git a/versions/1.2.0-dev.md b/versions/1.2.0-dev.md
index 7f771e7..c258797 100644
--- a/versions/1.2.0-dev.md
+++ b/versions/1.2.0-dev.md
@@ -21,7 +21,7 @@ The main purpose of the Overlay Specification is to provide a way to repeatably
### Overlay
-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.
+An Overlay is represented in JSON or YAML and contains [actions](#overlay-actions) that are applied in order to an [[OpenAPI]] description. Each action uses a target expressed as a [[RFC9535|RFC9535 JSONPath]] query expression to identify where changes apply. [Reusable actions](#reusable-action-object) may be used to reduce duplication through references.
## Specification
@@ -33,7 +33,7 @@ The Overlay Specification is versioned using a `major`.`minor`.`patch` versionin
### Format
-An Overlay document that conforms to the Overlay Specification is itself a JSON object, which may be represented either in [[RFC8259|JSON]] or [[YAML|YAML]] format. Examples in this specification will be shown in YAML for brevity.
+An Overlay that conforms to the Overlay Specification is itself a JSON object, which may be represented either in [[RFC8259|JSON]] or [[YAML|YAML]] format. Examples in this specification will be shown in YAML for brevity.
Implementations MUST support applying either JSON or YAML Overlay documents to
[[OpenAPI|OpenAPI]] descriptions
@@ -84,7 +84,8 @@ This is the root object of the [Overlay](#overlay).
| 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. |
| info | [Info Object](#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](#action-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
+| actions | [[Action Object](#action-object) \| [Reusable Action Reference Object](#reusable-action-reference-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
+| components | [Components Object](#components-object) | A set of components to reuse across the Overlay Document. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -128,6 +129,20 @@ The metadata MAY be used by the clients if needed.
This object MAY be extended with [Specification Extensions](#specification-extensions).
+#### Components Object
+
+The object provides a set of components to be reused across the Overlay document.
+
+##### Fixed Fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| actions | Map(`string`, [Reusable Action Object](#reusable-action-object)) | A key-value set of reusable actions to reference in the actions through a [Reusable Action Reference Object](#reusable-action-reference-object). |
+
+When a key under `components.actions` is referenced by a Reusable Action Reference Object, that key is part of a JSON Pointer token and MUST be encoded according to [[RFC6901], Section 3](https://www.rfc-editor.org/rfc/rfc6901#section-3) (for example, `~` as `~0` and `/` as `~1`).
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
#### Action Object
This object represents one or more changes to be applied to the target document at the locations defined by the target JSONPath expression.
@@ -157,6 +172,42 @@ The properties of the `update` or `copy` object MUST be compatible with the targ
This object MAY be extended with [Specification Extensions](#specification-extensions).
+#### Reusable Action Object
+
+This object defines a reusable action in [`components.actions`](#component-actions).
+It can be referenced from [`actions`](#overlay-actions) by a [Reusable Action Reference Object](#reusable-action-reference-object).
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| description | `string` | A description of the reusable action. This description is independent of the `description` field on the contained [Action Object](#action-object) and is intended to document the reusable action itself (for example, its purpose or usage). [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
+| fields | [Action Object](#action-object) | An [Action Object](#action-object) where no field is required, except that the `target` field MUST NOT be provided. The `target` MUST be supplied by the [Reusable Action Reference Object](#reusable-action-reference-object). |
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
+A reusable action is similar to an action but differs in important ways:
+
+1. Action fields are nested inside the `fields` property, not defined as peer properties. The `fields` object may omit any action field, and MUST NOT include the `target` field; the `target` MUST be supplied by the [Reusable Action Reference Object](#reusable-action-reference-object).
+1. A Reusable Action Object has to be referenced by a Reusable Action Reference Object to have any effect on the OpenAPI description.
+
+#### Reusable Action Reference Object
+
+A Reusable Action Reference Object applies a reusable action defined in `components.actions` to a specific target in the source document.
+It references the reusable action by `$ref` and MAY provide action fields that override values from the referenced reusable action for that use.
+
+##### Fixed fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| $ref | `string` | **REQUIRED** A [same-document](https://www.rfc-editor.org/rfc/rfc3986.html#section-4.4) (or fragment-only) relative URI reference, per RFC3986 ยง4.4, where the fragment syntax is JSON Pointer with the pointer prefix restricted to `/components/actions/`. Component action keys in this pointer MUST be encoded according to [[RFC6901], Section 3](https://www.rfc-editor.org/rfc/rfc6901#section-3). |
+| target | `string` | **REQUIRED** A JSONPath query expression, as described in [[RFC9535]], referencing the target objects in the source document. |
+| description | `string` | A description of the action. [[CommonMark]] syntax MAY be used for rich text representation. |
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
+In case a description is defined in `fields` of the referenced [Reusable Action Object](#reusable-action-object) and in the Reference Object, the description from the Reference Object MUST be used.
+
### Examples
#### Structured Overlay Example
@@ -559,6 +610,97 @@ paths:
description: OK
```
+##### Reusable Action Reference Example - Overrides
+
+This example shows how a reusable action can provide shared update content while a reusable action reference supplies the `target` locally. In this case, each reference reuses the same error response definition but supplies a different `target` so the update is applied to different operations.
+
+###### Source Description
+
+```yaml
+openapi: 3.2.0
+info:
+ title: Example API
+ version: 1.0.0
+paths:
+ /items:
+ get:
+ responses:
+ 200:
+ description: OK
+ /some-items:
+ delete:
+ responses:
+ 200:
+ description: OK
+```
+
+###### Overlay
+
+```yaml
+overlay: 1.2.0
+info:
+ title: Use reusable actions to insert error responses
+ version: 1.0.0
+components:
+ actions:
+ errorResponse:
+ fields:
+ update:
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ description: Adds an error response to the operation
+actions:
+- $ref: '#/components/actions/errorResponse'
+ target: "$.paths['/items'].get.responses"
+- $ref: '#/components/actions/errorResponse'
+ target: "$.paths['/some-items'].delete.responses"
+```
+
+###### Result Description
+
+```yaml
+openapi: 3.2.0
+info:
+ title: Example API
+ version: 1.0.0
+paths:
+ /items:
+ get:
+ responses:
+ 200:
+ description: OK
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ /some-items:
+ delete:
+ responses:
+ 200:
+ description: OK
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+```
+
### Specification Extensions
While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.