clarification about YAML

[fehguy]

Fixes #575

[jharmn]

There is one mention of YAML anchors in REUSE.md, we might want to be sure to either clarify it there, or link to this section.
https://github.com/OAI/OpenAPI-Specification/blob/3cb58cd1da4051d9d3d5401b9fa7eb7abe70dc90/guidelines/REUSE.md#yaml-example

[webron]

Better add the clarification than link to an extra document we produced ourselves. It's a bit too meta ;)

[earth2marsh]

All numeric keys must be quoted would be stronger.

[ePaul]

Actually we mean "All keys must be strings" here, and "Keys looking like a number need to be quoted to be a string" is just a hint to the reader on how to implement this.

[fehguy]

@OAI/tdc decided that @webron will review the YAML spec before we move on this

[darrelmiller]

@webron I'm happy to give you a hand wading through issues related to the YAML spec. I actually liked the spec last time I read it. It has a certain style that takes a bit of getting used to but I found it very consistent.

[ePaul]

Maybe add a link to the spec?

I don't find "Merge" in that document, does it have a different name there?

[darrelmiller]

Apparently it was defined in a separate doc http://yaml.org/type/merge.html

[ePaul]

Ah. This seems actually useful – maybe suggest using a preprocessor to resolve it (thereby eliminating the need to deal with it in the spec, but still allowing to use it for users?)

[fehguy]

@ePaul you can preprocess whatever you like in a tool, but per the spec--as I'm trying to make extremely explicit, merge is NOT supported.

[webron]

@darrelmiller Thanks! Would appreciate the extra pair of eyes.

[webron]

Suggest we keep this one open for a bit until @darrelmiller and I (and of course anyone else in the TDC who'd like to read it) have a chance to go over the YAML spec and propose additional clarifications. I don't think this delays the progress of work on 3.0.

[fehguy]

@OAI/tdc please approve or reject

[fehguy]

If this requires an additional review as @webron states, let's do it. But I don't want this issue staying open much longer

[webron]

I think it does, but I won't get around to diving into the YAML spec before next week.

[earth2marsh]

Quoting numeric keys makes complete sense to me.
Merge still falls into a similar category to comments—OAS cannot support the round-tripping between JSON and YAML. In this case, it's still fine to recommend using JSON Pointers instead but make the distinction that merge and comments both will be lost in conversion.

[darrelmiller]

Here are my thoughts on the subject:

I think we should reference YAML 1.2 instead of 1.1

• The YAML 1.2 spec hasn't changed since 2009.
• There are multiple changes in 1.2 that address JSON compatibility
• RAML references 1.2
• Maybe if there is more demand for 1.2 support, the YAML toolkits will update. 1.2 is not a big change from 1.1
• The 1.2 spec seems quite a bit more readable than the 1.1 version.

The constraint on keys should read something like:
Mapping keys should be either plain strings or quoted scalar values to facilitate translation to JSON.

The use of Tags should be limited to the JSON schema to ensure JSON interoperability.

[whitlockjc]

I agree with @darrelmiller. I like the idea that JSON is the compatibility layer and whatever in YAML that breaks JSON/JSON Schema compatibility should be unsupported.

[darrelmiller]

In the .net space there is a 1.2 compliant parser called SharpYaml and I think it was @whitlockjc that mentioned that the JS library they are using supports 1.2. I suspect the tooling list at https://yaml.org is just out-dated.

[darrelmiller]

I have updated the text to what I believe covers all the issues. I removed the comment about the merge key value because that is a key value that is not defined by the JSON schema ruleset in YAML so therefore is automatically disallowed. I also removed the constraint regarding numeric keys needing to be quoted because numeric keys are valid in both JSON and YAML and will convert seamlessly. I did add a constraint to ensure keys cannot be non-scalar values, which is something that does not convert into JSON.

[ePaul]

I also removed the constraint regarding numeric keys needing to be quoted because numeric keys are valid in both JSON and YAML and will convert seamlessly.

Hmm, are you knowing a different JSON than me? Looking at JSON.org, the key in an object needs to be a string, not a number.

[darrelmiller]

@ePaul My bad. Spending too much time switching between specs and I got confused. I'll fix it.

[webron]

After talking with one of YAML's authors - let's stick with 1.2. It will hopefully also drive 1.2 implementations.

As for the issue regarding the values of On, Off, Yes, No.... as true or false - it's an opt-in feature, so let's just not opt in. Again, will be slightly challenging with implementations, but it makes more sense.

[ePaul]

@webron Does it make sense to explicitly mention this boolean issue so implementors pay attention to it (and configure their YAML processors to not do this)?

[darrelmiller]

@ePaul My comment about needing to only use tags from the JSON Schema was my attempt to be explicit about this.

Tags MUST be limited to those allowed by the [JSON Schema ruleset](

Do you think it is necessary to call out specific literals that are and are not allowed?

[ePaul]

Hmm, I don't know enough about YAML to be able to competently answer this – I hope OpenAPI tooling authors who support YAML know it better. I just observed once someone using OFF as an enum element and wondering why he got problems with code generation (with Swagger 2.0) – that OFF was interpreted as false, and the generator didn't support non-string values.