Skip to content

feat: clarifies format interoperability #246

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: clarifies format interoperability #246

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cca675
feat: clarifies format interoperability
baywet Nov 20, 2025
2aa88d0
Update versions/1.1.0-dev.md
baywet Nov 23, 2025
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
26 changes: 22 additions & 4 deletions versions/1.1.0-dev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,33 @@ 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.
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.

All field names in the specification are **case sensitive**.
This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.

In order to preserve the ability to round-trip between YAML and JSON formats, [[YAML|YAML version 1.2]] is RECOMMENDED along with some additional constraints:
Overlay [schema](#schema) expose two types of fields: _fixed fields_, which have a declared name, and _patterned fields_, which have a declared pattern for the field name.

- 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).
Patterned fields MUST have unique names within the containing object.

#### JSON and YAML Compatibility

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with the additional constraints listed in [[!RFC9512]] [Section 3.4](https://www.rfc-editor.org/rfc/rfc9512.html#name-yaml-and-json).

The recommendation in previous versions of this specification to restrict YAML to its "JSON" [schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231) allowed for the inclusion of certain values that (despite the name) cannot be represented in JSON.
Overlay authors SHOULD NOT rely on any such JSON-incompatible YAML values.
Copy link
Contributor

@lornajane lornajane Nov 23, 2025

Choose a reason for hiding this comment

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

Previously we mentioned these as being tags and scalar keys. While I'm sure this reference is entirely correct and comprehensive, could we keep the high-level explanation as well to help people understand what kinds of things to look out for?

Copy link
Member

@handrews handrews Nov 23, 2025

Choose a reason for hiding this comment

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

@lornajane this change brings it into alignment with OAS 3.2. The previous language was not only confusing but actually incorrect. Fortunately, almost no one paid attention to it. The part about tags was particularly baffling, IIRC.

Copy link
Member

@handrews handrews Nov 23, 2025

Choose a reason for hiding this comment

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

I think the important thing here is to use the same wording across all three specs.


#### Case Sensitivity

As most field names and values in the Overlay Specification are case-sensitive, this document endeavors to call out any case-insensitive names and values.

#### Rich Text Formatting

Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
Where Overlay tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark or extension features to address security concerns.

While the framing of CommonMark 0.27 as a minimum requirement means that tooling MAY choose to implement extensions on top of it, note that any such extensions are by definition implementation-defined and will not be interoperable.
Overlay Description authors SHOULD consider how text using such extensions will be rendered by tools that offer only the minimum support.

### Relative References in URIs

Expand Down