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

Jump to bottom

Updated use of URL to URI #76

Merged
merged 3 commits into from
Oct 15, 2024
Merged

Updated use of URL to URI #76

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
471067a
Updated use of URL
darrelmiller Oct 12, 2024
2ec603f
Added comma
darrelmiller Oct 12, 2024
299b643
Update versions/1.0.0.md
ralfhandl Oct 14, 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
11 changes: 5 additions & 6 deletions versions/1.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,9 @@ 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).

### Relative References in URLs
### Relative References in URIs

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).
Unless specified otherwise, relative references are resolved using the URL of the referring document.
Unless specified otherwise, all fields that are URI references MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to say what the Base URI is here? I think we do in the OAS.

Copy link
Member

@handrews handrews Oct 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikekistler no, because RFC3986 takes care of it, and the Overlay Specification does not define an internal base URI-setting mechanism under RFC3986 §5.1.1. Most of the weird problems regarding base URIs in the OpenAPI Specification are because someone tried to re-write things already covered by RFC3986 and messed it up (e.g. forgetting about §5.1.2, or creating ambiguity around the term "document'), so let's not do that here. Just referencing RFC3986 is sufficient.


### Schema

Expand All @@ -65,7 +64,7 @@ This is the root object of the [Overlay](#overlay).
| ---- | :----: | ---- |
| <a name="overlay-version"></a>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. |
| <a name="overlay-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. |
| <a name="overlay-extends"></a>extends | `string` | URL to the target document (such as an [[OpenAPI]] document) this overlay applies to. This MUST be in the form of a URL. |
| <a name="overlay-extends"></a>extends | `string` | URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to. |
| <a name="overlay-actions"></a>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. |

This object MAY be extended with [Specification Extensions](#specification-extensions).
Expand All @@ -74,7 +73,7 @@ The list of actions MUST be applied in sequential order to ensure a consistent o

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

In the following example the `extends` property specifies that the overlay is designed to update the OpenAPI Tic Tac Toe example document using an absolute URL.
In the following example the `extends` property specifies that the overlay is designed to update the OpenAPI Tic Tac Toe example document, identified by an absolute URI.

```yaml
overlay: 1.0.0
Expand All @@ -85,7 +84,7 @@ extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/ma
...
```

The `extends` property can also specify a relative URL. In this case, the URL is resolved relative to the location of the Overlay document.
The `extends` property can also specify a relative URI reference.

```yaml
overlay: 1.0.0
Expand Down