diff --git a/versions/1.2.0-dev.md b/versions/1.2.0-dev.md index 7f771e7..902b57c 100644 --- a/versions/1.2.0-dev.md +++ b/versions/1.2.0-dev.md @@ -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) or [Action Template Reference Object](#action-template-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. Optional. | 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 | +| ---- | :----: | ---- | +| actionTemplates | Map(`string`, [Action Template Object](#action-template-object)) | A key-value set of action templates to reference in the actions. Optional. | + +> Note: the target field for components actions is Optional. + +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,72 @@ The properties of the `update` or `copy` object MUST be compatible with the targ This object MAY be extended with [Specification Extensions](#specification-extensions). +#### Action Template Object + +This object represents one or more changes to be applied to the target document at the locations defined by the target JSONPath expression and reused in one of more action references. + +##### Fixed fields + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| parameters | [[Action template parameter object](#action-template-parameter-object)] | A list of parameters to be used during string literal replacement. Optional. | +| environmentVariables | [[Action template parameter object](#action-template-parameter-object)] | A list of environment variables to be used during string literal replacement. Optional. | +| Any field defined in the [action object](#action-object) | mixed | The [string literal replacement syntax](#string-literal-replacement-syntax) MAY be used for any of the fields, and the replacements MUST be evaluated as the template reference is being resolved. | + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +#### Action Template Parameter Object + +##### Fixed fields + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| name | `string` | **REQUIRED** The name of the parameter, MUST match the key for the string literal replacement expression. | +| $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, and that the fragment syntax is JSON Pointer, with the pointer prefix restricted to `/components/actionTemplates/`. | +| Any field defined in the [action object](#action-object) | mixed | Any field defined in the [Action Object](#action-object) to be used as an override to the value resolved in the template. The [string literal replacement syntax](#string-literal-replacement-syntax) MAY NOT be used for any of the fields. Optional. | + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +### String Literal Replacement Syntax + +The following string replacement syntax MAY be used: + +%source.key% + +Where **source** is a known source whose value MUST ONLY be **env** for environment variables, or **param** for parameters. The key MUST only contain the following characters A-Za-z0-9, contain at least one character and start with a letter. + +#### ABNF Notation + +```abnf +replacement-string = "%" source "." key "%" +source = "env" / "param" +key = ALPHA *( ALPHA / DIGIT ) +``` + +Where ALPHA and DIGIT rules are defined in [[RFC5234]]. + +#### Environment Replacement Source + +When the environment replacement source is used, the key MUST match (case-sensitive) an environment variable defined for the process parsing the Overlay document. If the environment variable is not defined, the processor MAY either replace it with an empty string or return an error. + +#### Parameter Replacement Source + +When the parameter replacement source is used, the key MUST match (case-sensitive) a corresponding parameter defined for the action template. + + ### Examples #### Structured Overlay Example @@ -559,6 +640,204 @@ paths: description: OK ``` +##### Action Template Reference Example - Overrides + +###### 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 templates to insert error responses + version: 1.0.0 +components: + actionTemplates: + errorResponse: + update: + 404: + description: Not Found + application/json: + schema: + type: object + properties: + message: + type: string + target: "$.paths['placeholder'].get.response" + description: Adds an error response to the %param.pathItem% path item %param.operation% operation +actions: +- $ref: '#/components/actions/errorResponse' + # the target from the action template is being superseded by this local override value + target: "$.paths['items'].get.responses" +- $ref: '#/components/actions/errorResponse' + # the target from the action template is being superseded by this local override value + 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 + application/json: + schema: + type: object + properties: + errorMessage: + type: string + /some-items: + delete: + responses: + 200: + description: OK + 404: + description: Not Found + application/json: + schema: + type: object + properties: + deleteErrorMessage: + type: string +``` + +##### Action Template Example - Parameters + +###### 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 templates to insert error responses + version: 1.0.0 +components: + actionTemplates: + errorResponse: + target: "$.paths['%param.pathItem%'].%param.operation%.responses" + update: + 404: + description: Not Found + application/json: + schema: + type: object + properties: + '%param.propertyName%': + type: string + stageName: + type: string + const: '%env.stageName%' + description: Adds an error response to the %param.pathItem% path item %param.operation% operation + parameters: + - name: pathItem + - name: operation + default: get + - name: propertyName + default: errorMessage + environmentVariables: + - name: stageName + default: dev +actions: +- $ref: '#/components/actionTemplates/errorResponse' + parameterValues: + pathItem: '/items' +- $ref: '#/components/actionTemplates/errorResponse' + parameterValues: + pathItem: '/some-items' + operation: delete + propertyName: deleteErrorMessage +``` + +> Note: in this example, no value is set for the process environment variable "stageName". + +###### 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 + application/json: + schema: + type: object + properties: + errorMessage: + type: string + stageName: + type: string + const: dev + /some-items: + delete: + responses: + 200: + description: OK + 404: + description: Not Found + application/json: + schema: + type: object + properties: + deleteErrorMessage: + type: string + stageName: + type: string + const: dev +``` + ### Specification Extensions While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.