From 0cca675cab1b77fc152c66b95e2a2e4dc29072d8 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 20 Nov 2025 09:09:04 -0500 Subject: [PATCH 1/2] feat: clarifies format interoperability Signed-off-by: Vincent Biret --- versions/1.1.0-dev.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 0923540..0e09ff0 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -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. + +#### 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 From 2aa88d0edd31c90edda2f66c8ebbea4f0c9b3d18 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Sun, 23 Nov 2025 09:57:16 -0500 Subject: [PATCH 2/2] Update versions/1.1.0-dev.md Co-authored-by: Ralf Handl --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 0e09ff0..42e34b8 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -38,7 +38,7 @@ An Overlay document that conforms to the Overlay Specification is itself a JSON 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**. -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. +The Overlay [schema](#schema) defines two types of fields: _fixed fields_, which have a declared name, and _patterned fields_, which have a declared pattern for the field name. Patterned fields MUST have unique names within the containing object.