Remove emphasis on human readability from documentation about www.yaml.org HOT 7 CLOSED

YAML has lost its way on human readability.

I don't think that this is the case, but if you believe that, it doesn't need to imply that we should "remove emphasis on human readability from documentation". A more constructive alternative is to identify places where YAML is deviating from this goal and find ways to steer it back towards it.

from www.yaml.org.

YAML has lost its way on human readability.

I find it very readable, and I am glad that many apps support YAML as a format.
Which format would you prefer for things like CircleCI, GitHub Workflows, Travis CI, Ansible etc.?

When a single space or leading 0 on a number can fundamentally change the outcome

1. a space in the wrong place can also break a python script. That's the point of an indentation based language.
2. a leading 0 on a number does not change the result in YAML 1.2.

from www.yaml.org.

I don't honestly expect my concern to be taken seriously but assuming you're responding in good faith I will engage.

The applications you mentioned are ones that benefit from an expressive data format which I admit YAML can be.

To the second point, python is a general purpose dynamic programming language and therefore an exacting syntax is expected.

Your second example is the exact reason my comment stands. The 1.2 spec allowing octals to be represented by 0o is a correction to the questionable decision of previously representing them with a leading 0, which is not in keeping with how humans read numbers. Secondly since YAML files aren't explicitly versioned you can't safely use a 0-leading number unless you can be sure it will be read by a 1.2 enabled parser.

This is just the tip of the iceberg for the other syntax features available in YAML, none of which are established human linguistic constructs.

So I say again, let's just lean into it and acknowledge YAML as a powerful and expressive format with a learning curve instead of pretending that it's somehow intuitive and trying to define it in opposition to JSON and XML, because at the moment YAML has more syntax and complexity than the two of them combined.

from www.yaml.org.

Secondly since YAML files aren't explicitly versioned you can't safely use a 0-leading number unless you can be sure it will be read by a 1.2 enabled parser.

YAML files can be versioned, and there are more and more processors developed that are capable of loading YAML 1.2.
Here is an example of the commandline tool for my YAML::PP processor:

% echo '%YAML 1.1
---
- 010
...
%YAML 1.2
---
- 010
' | yamlpp-load --yaml-version=1.2,1.1
$doc0 = [
          8
        ];
$doc1 = [
          10
        ];

A list of processors that support the YAML 1.2 Core schema and YAML 1.1 types like that so far:

• https://github.com/eemeli/yaml
• https://bitbucket.org/ruamel/yaml
• https://metacpan.org/release/YAML-PP

YAML 1.2 was invented to improve such things, and the only problem is that there are many processors out there that don't support it yet.
So can we get at least the "leading zero" thing out of the discussion please? :)

I'm planning to add information like this to https://www.yaml.info/libraries/index.html, and we're hoping to get more developers on board to support 1.2.

from www.yaml.org.

none of which are established human linguistic constructs.

This is how a handwritten birthday party check list could look like:

Food:
- Onions
- Curly cale
- Paprika
- Tahini

Drinks:
- Juice
- Lemonade
- Water

That's perfectly valid YAML :)

from www.yaml.org.

@aaubry

I don't think that this is the case, but if you believe that, it doesn't need to imply that we should "remove emphasis on human readability from documentation". A more constructive alternative is to identify places where YAML is deviating from this goal and find ways to steer it back towards it.

Unfortunately that ship has sailed and increasing human readability while maintaining the current function set would require adding more syntax and complexity. Therefore I do not believe that your "constructive alternative" is really viable. That said, please consider, if YAML were not widely thought of as "being more human readable than JSON" would it cease to have value? Does JSON make a big deal about its human readability? Then it stands to reason that YAML can refer to human readability as a historical design goal, without losing anything.

I would also remind you that YAML redefined its own acronym! So this shouldn't be a big deal and we can stop trying to gaslight the world about human readability.

@perlpunk
Again, your YAML 1.2 example only works on a 1.2 parser, on a 1.0 or 1.1 parser it returns an unexpected result. It's not a saving grace, it's a condemnation.

Your checklist example is a purposefully basic one. I ask you, what are these syntax symbols?

--- >
--- |
&pat
*pat
?:

Do you think these are immediately obvious? If not that's a learning curve and cognitive load.

So in conclusion, YAML should just acknowledge that to become a flexible and powerful data format required making compromises to syntax readability that have already been done. It would simply be more honest to de-emphasize "human readability" as it doesn't change it's usefulness or adoption.

from www.yaml.org.

This repository is only regarding https://yaml.org content.
The spec is published from here but the sources are at https://github.com/yaml/yaml-spec

from www.yaml.org.