Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor nits #62

Merged
merged 3 commits into from
Oct 7, 2024
Merged

Minor nits #62

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
78e3a3d
Minor nits
ralfhandl Sep 25, 2024
945c0b6
Update 1.0.0.md
ralfhandl Sep 25, 2024
de2b9ff
Remove section on file names for Overlay documents
ralfhandl Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions versions/1.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,6 @@ In order to preserve the ability to round-trip between YAML and JSON formats, [[
- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).

### Document Structure

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

### Relative References in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
Expand All @@ -70,9 +66,9 @@ This is the root object of the [Overlay](#overlay).

This object MAY be extended with [Specification Extensions](#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 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 documents to the appropriate OpenAPI document(s).
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).

#### Info Object

Expand Down Expand Up @@ -107,7 +103,7 @@ To update a primitive property value such as a string, the `target` expression s

Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced.

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 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](#specification-extensions).

Expand Down Expand Up @@ -209,7 +205,7 @@ actions:
remove: true
```

#### Traits Examples
#### 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.

Expand Down