Merge pull request #246 from baywet/feat/round-trip-yaml

feat: clarifies format interoperability

Author: baywet

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:
+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.
 
-- 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