From 6e00d2612e2ce122f3f1155dc0c2c0ccacc0de8d Mon Sep 17 00:00:00 2001 From: lornajane <172607+lornajane@users.noreply.github.com> Date: Tue, 8 Oct 2024 15:08:00 +0000 Subject: [PATCH] Update ReSpec-rendered specification versions Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- overlay/latest.html | 57 ++++++++++++++++++++------------------------- overlay/v1.0.0.html | 57 ++++++++++++++++++++------------------------- 2 files changed, 50 insertions(+), 64 deletions(-) diff --git a/overlay/latest.html b/overlay/latest.html index 5628d68778..5427a0c5f5 100644 --- a/overlay/latest.html +++ b/overlay/latest.html @@ -80,8 +80,7 @@ - +

What is the Overlay Specification?

-

The Overlay Specification is an extension or companion to the [OpenAPI] specification. -An Overlay describes a set of changes to be applied or “overlaid” onto an existing OpenAPI description.

-

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.

-

Status of This Document

The source-of-truth for this specification is the HTML file referenced above as This version.
+

The Overlay specification defines a way of creating documents that contain information to be merged with an [OpenAPI] Description at some later point in time, for the purpose of updating the OpenAPI description with additional information.

+

Status of This Document

The source-of-truth for this specification is the HTML file referenced above as This version.

1. Overlay Specification

1.1 Version 1.0.0

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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

@@ -250,16 +245,14 @@

Overlay Specification v1.0.0

MUST be limited to those allowed by the JSON Schema ruleset.
  • Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
    • -

    4.3 Document Structure

    -

    It is RECOMMENDED that the root Overlay document be named: overlay.json or overlay.yaml.

    -

    4.4 Relative References in URLs

    +

    4.3 Relative References in URLs

    Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2. Unless specified otherwise, relative references are resolved using the URL of the referring document.

    -

    4.5 Schema

    +

    4.4 Schema

    In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

    -

    4.5.1 Overlay Object

    +

    4.4.1 Overlay Object

    This is the root object of the Overlay.

    -
    4.5.1.1 Fixed Fields
    +
    4.4.1.1 Fixed Fields
    @@ -292,12 +285,12 @@

    Overlay Specification v1.0.0

    MAY be extended with Specification Extensions.

    -

    The list of actions MUST be applied in sequential order to ensure a consistent outcome. Actions 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, for example.

    -

    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 documents to the appropriate OpenAPI document(s).

    -

    4.5.2 Info Object

    +

    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.

    +

    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).

    +

    4.4.2 Info Object

    The object provides metadata about the Overlay. The metadata MAY be used by the clients if needed.

    -
    4.5.2.1 Fixed Fields
    +
    4.4.2.1 Fixed Fields

    @@ -320,9 +313,9 @@

    Overlay Specification v1.0.0

    MAY be extended with Specification Extensions.

    -

    4.5.3 Action Object

    +

    4.4.3 Action Object

    This object represents one or more changes to be applied to the target document at the location defined by the target JSONPath expression.

    -
    4.5.3.1 Fixed Fields
    +
    4.4.3.1 Fixed Fields

    @@ -357,10 +350,10 @@

    Overlay Specification v1.0.0

    MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object.

    +

    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 replace properties in the target object with the same name and new properties are appended to the target object.

    This object MAY be extended with Specification Extensions.

    -

    4.6 Examples

    -

    4.6.1 Structured Overlays Example

    +

    4.5 Examples

    +

    4.5.1 Structured Overlays Example

    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.

    overlay: 1.0.0
 info:
@@ -384,7 +377,7 @@ 
    Overlay Specification v1.0.0 
     
    components:
       tags:
    -

    4.6.2 Targeted Overlays

    +

    4.5.2 Targeted Overlays

    Alternatively, where only a small number of updates need to be applied to a large document, each Action Object MAY be more targeted.

    overlay: 1.0.0
 info:
@@ -403,7 +396,7 @@ 
    Overlay Specification v1.0.0 
     
    description: This is an updated description of a child object
         x-safe: false
    -

    4.6.3 Wildcard Overlays Examples

    +

    4.5.3 Wildcard Overlays Examples

    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.

    overlay: 1.0.0
 info:
@@ -418,7 +411,7 @@ 
    Overlay Specification v1.0.0 
     
    schema:
         $ref: '/components/schemas/filterSchema'
    -

    4.6.4 Array Modification Examples

    +

    4.5.4 Array Modification Examples

    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.

    overlay: 1.0.0
 info:
@@ -438,7 +431,7 @@ 
    Overlay Specification v1.0.0 
     
    - target: $.paths.*.get.parameters[?@.name == 'dummy']
     remove: true
    -

    4.6.5 Traits Examples

    +

    4.5.5 Traits Example

    By annotating a target document (such as an [OpenAPI] document) using specification extensions such as x-oai-traits, the author of the target document MAY identify where overlay updates should be applied.

    openapi: 3.1.0
 info:
@@ -469,7 +462,7 @@ 
    Overlay Specification v1.0.0 
     
    # ...

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

    -

    4.7 Specification Extensions

    +

    4.6 Specification Extensions

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

    The extension properties are implemented as patterned fields that are always prefixed by "x-".

    diff --git a/overlay/v1.0.0.html b/overlay/v1.0.0.html index 5628d68778..5427a0c5f5 100644 --- a/overlay/v1.0.0.html +++ b/overlay/v1.0.0.html @@ -80,8 +80,7 @@ - +

    What is the Overlay Specification?

    -

    The Overlay Specification is an extension or companion to the [OpenAPI] specification. -An Overlay describes a set of changes to be applied or “overlaid” onto an existing OpenAPI description.

    -

    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.

    -

    Status of This Document

    The source-of-truth for this specification is the HTML file referenced above as This version.
    +

    The Overlay specification defines a way of creating documents that contain information to be merged with an [OpenAPI] Description at some later point in time, for the purpose of updating the OpenAPI description with additional information.

    +

    Status of This Document

    The source-of-truth for this specification is the HTML file referenced above as This version.

    1. Overlay Specification

    1.1 Version 1.0.0

    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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

    @@ -250,16 +245,14 @@

    Overlay Specification v1.0.0

    MUST be limited to those allowed by the JSON Schema ruleset.
  • Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.
    • -

    4.3 Document Structure

    -

    It is RECOMMENDED that the root Overlay document be named: overlay.json or overlay.yaml.

    -

    4.4 Relative References in URLs

    +

    4.3 Relative References in URLs

    Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2. Unless specified otherwise, relative references are resolved using the URL of the referring document.

    -

    4.5 Schema

    +

    4.4 Schema

    In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

    -

    4.5.1 Overlay Object

    +

    4.4.1 Overlay Object

    This is the root object of the Overlay.

    -
    4.5.1.1 Fixed Fields
    +
    4.4.1.1 Fixed Fields
    @@ -292,12 +285,12 @@

    Overlay Specification v1.0.0

    MAY be extended with Specification Extensions.

    -

    The list of actions MUST be applied in sequential order to ensure a consistent outcome. Actions 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, for example.

    -

    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 documents to the appropriate OpenAPI document(s).

    -

    4.5.2 Info Object

    +

    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.

    +

    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).

    +

    4.4.2 Info Object

    The object provides metadata about the Overlay. The metadata MAY be used by the clients if needed.

    -
    4.5.2.1 Fixed Fields
    +
    4.4.2.1 Fixed Fields

    @@ -320,9 +313,9 @@

    Overlay Specification v1.0.0

    MAY be extended with Specification Extensions.

    -

    4.5.3 Action Object

    +

    4.4.3 Action Object

    This object represents one or more changes to be applied to the target document at the location defined by the target JSONPath expression.

    -
    4.5.3.1 Fixed Fields
    +
    4.4.3.1 Fixed Fields

    @@ -357,10 +350,10 @@

    Overlay Specification v1.0.0

    MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object.

    +

    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 replace properties in the target object with the same name and new properties are appended to the target object.

    This object MAY be extended with Specification Extensions.

    -

    4.6 Examples

    -

    4.6.1 Structured Overlays Example

    +

    4.5 Examples

    +

    4.5.1 Structured Overlays Example

    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.

    overlay: 1.0.0
 info:
@@ -384,7 +377,7 @@ 
    Overlay Specification v1.0.0 
     
    components:
       tags:
    -

    4.6.2 Targeted Overlays

    +

    4.5.2 Targeted Overlays

    Alternatively, where only a small number of updates need to be applied to a large document, each Action Object MAY be more targeted.

    overlay: 1.0.0
 info:
@@ -403,7 +396,7 @@ 
    Overlay Specification v1.0.0 
     
    description: This is an updated description of a child object
         x-safe: false
    -

    4.6.3 Wildcard Overlays Examples

    +

    4.5.3 Wildcard Overlays Examples

    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.

    overlay: 1.0.0
 info:
@@ -418,7 +411,7 @@ 
    Overlay Specification v1.0.0 
     
    schema:
         $ref: '/components/schemas/filterSchema'
    -

    4.6.4 Array Modification Examples

    +

    4.5.4 Array Modification Examples

    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.

    overlay: 1.0.0
 info:
@@ -438,7 +431,7 @@ 
    Overlay Specification v1.0.0 
     
    - target: $.paths.*.get.parameters[?@.name == 'dummy']
     remove: true
    -

    4.6.5 Traits Examples

    +

    4.5.5 Traits Example

    By annotating a target document (such as an [OpenAPI] document) using specification extensions such as x-oai-traits, the author of the target document MAY identify where overlay updates should be applied.

    openapi: 3.1.0
 info:
@@ -469,7 +462,7 @@ 
    Overlay Specification v1.0.0 
     
    # ...

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

    -

    4.7 Specification Extensions

    +

    4.6 Specification Extensions

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

    The extension properties are implemented as patterned fields that are always prefixed by "x-".