YAML presentation ("cosmetic") controls

[VladimirAlexiev]

As an information architect.
When serializing YAML.
I want control over all YAML presentation ("cosmetic") features.
So that I can obtain a YAML representation that is most readable and usable for my case.

What "cosmetic" features do I mean:

• optional header --- and footer ...
• Number of spaces used to indent
• Use of flow-style vs block-style for particular pieces of YAML
• Ordering of keys
• Alias names
• Formatting of text blocks
• String quoting
• Use of escapes and code points in strings
• Serialization of booleans
• etc etc

How to list all controllable features systematically?

• https://yaml.org/spec/1.2.2/#presenting-the-serialization-tree
• https://yaml.org/spec/1.2.2/#323-presentation-stream

Here are the options of some serializers:

• https://metacpan.org/dist/YAML/view/lib/YAML.pod#GLOBAL-OPTIONS
• https://metacpan.org/dist/YAML-LibYAML/view/lib/YAML/XS.pod#CONFIGURATION
• https://metacpan.org/pod/YAML::Syck#FLAGS
• https://metacpan.org/pod/YAML::PP#preserve, https://metacpan.org/pod/YAML::PP#preserved_scalar, https://metacpan.org/pod/YAML::PP#preserved_mapping,-preserved_sequence
• https://metacpan.org/dist/YAML-Dump/view/lib/YAML/Dump.pod#INDENT
• https://pyyaml.org/wiki/PyYAMLDocumentation#cb66-4

Most of these are for Perl, could you please add links to serializers in other languages?

Maybe we should also turn to linters. https://megalinter.github.io/latest/descriptors/yaml/ can use 3 YAML linters:

• prettier: https://prettier.io/docs/en/options.html
• yamllint: https://yamllint.readthedocs.io/en/stable/rules.html, https://yamllint.readthedocs.io/en/stable/configuration.html
• v8r: https://github.com/chris48s/v8r#readme. This is a validator against schemas at www.schemastore.org , not a linter

Finally, this specifically aims to fix presentation, but currently has a somewhat limited set of options

• https://perlpunk.github.io/yamltidy/, eg https://perlpunk.github.io/yamltidy/seqindent.html. https://github.com/perlpunk/yamltidy/blob/master/.yamltidy

[ioggstream]

@VladimirAlexiev do you think we should define a recommended serialization for YAML-LD, or just to define a linter configuration for this repo (:+1: ) ?

I think YAML serialization configuration should be delegated to YAML and implementations, because they will improve over time.

An interesting caveat is instead the one related to multiple documents in the same stream, e.g.

---
a: 1
...
---
a: 2
...

[VladimirAlexiev]

@ioggstream We should definitely use a consistent style of all our examples, so we need a linter configuration for this repo.

serialization configuration should be delegated to YAML and implementations,

Maybe. However:

• The JSON-LD Context defines a lot about the form of serialized JSON: in fact all information aspects, but no presentation aspects.
• If the primary goal of YAML-LD is readability, why shouldn't presentation aspects be part of a "YAML-LD Context" (YAML-LD context and frame #44)?

[gkellogg]

I think adopting a consistent style for our examples is important, but 👎 on putting anything about a required style in the spec itself. In any case, that should be a YAML concern, not a YAML-LD concern.

[OR13]

I'm struggling to grok exactly what is proposed here, but I interpret this as a call for supporting the "non round trip-able to JSON features"... which I am in favor of... just we need to start using unique names for both cases.

I suggest we just start considering them different media types...

application/ld+yaml vs application/ld+json+yaml.

One is JSON-LD round trip-able... the other is not.

application/ld+yaml should allow for cosmetic features... +1 to the proposal.

[ioggstream]

@OR13 I will vote after the testcases are written :) These days I'm struggling even with very simple issues like extending fragment identification to YAML streams ietf-wg-httpapi/mediatypes#55 since I just discovered that future versions of YAML might consider that docs in a stream are not independent :P

[VladimirAlexiev]

I agree with @gkellogg and @ioggstream that the spec shouldn't claim any required style. But it can point to a linter configuration as a useful resource.

[gkellogg]

I agree with @gkellogg and @ioggstream that the spec shouldn't claim any required style. But it can point to a linter configuration as a useful resource.

Any such mechanism should probably work for JSON as well. But, I'm not aware of any such convention, or how we might signal that, other than through API extensions.

[gkellogg]

Discussed at TPAC F2F and resolved to close as out-of-scope.

[VladimirAlexiev]

@gkellogg

such mechanism should probably work for JSON as well

YAML has a lot more formatting options, eg to limit display line length of strings.
In JSON you can only vary the indentation and newlines.