A simple change of the typical top-level structure display from invalid JSON to valid YAML.

In case we like the way it renders the spec more readable (outlines instead of broken and noisy JSON), we can already use that in the upcoming CSAF v2.1 CSD for January 2026. Please cf. [CSAF-CD25] on the rationale behind this proposal.

Enhancements

• using additive instead of subtractive modeling for presenting the necessary and sufficient information to convey security advisories and the like.
• the additive outline presentation is closer to how modeling in general programming languages works
• no more "why provide the JSON schema a second time - per (invalid) snippets in the prose?" questions.
• use of JSON Path standard queries to link from information model to JSON schema content responsible for "allowing" that information
• the YAML outline-like snippets are accessible for validation
  • we can create isolated files following an easy hierarchical naming scheme
• less noisy by removing braces, brackets, and (most) double quotes
• outlines (indentation as hierarchical / scope indicator) are a centuries old writing device
• less misleading by removing the constant curly braces in the JSON Schemaesque displays
• more to the point directly indicating the shape of types in collapsed regions per the readable names:
  • Mapping
  • Sequence
  • String
• because of the reduction in "vertical space used", we can:
  • add the path to the root regardless of the location in the tree
  • replace the overly generic tiems and property layers in the outlines with
    • injecting a named instance placeholder in angle brackets
    • direct unfolding for properties
    • end of line comments cause less lines blow-up, because there are no brace pairs they have to go between on their own line

Examples

To keep this proposal comment box at reasonable "summary" length the examples are in a comment below.

References

[CSAF-CD25]: "Security Advisories - Facts, Fashions, and Fiction", Stefan Hagen, 2025-11-14, TLP:CLEAR, talk held at CSAF Community Days 2025, in Nuremberg, Germany, URL: https://stefan-hagen.website/security-advisories_facts-fashions-and-fiction.pdf