Commented on https://gist.github.com/trans/c28a41353d76a7b78bef

Basically we have a set of concerns that can effect the usage/processing of a YAML stream; version, tag-expansion, schema, emitter/formatter rules, etc. Each of these concerns can be expressed in YAML and can live in a separate document that is somehow associated with the YAML to be processed. The association can be a separate relative file, and in-stream YAML document, internal to the YAML framework logic or something else. The inline association is nice for things like tags, but things like schemas likely want to be external and reusable.

We have the following tags (at a minimum) that we can add to the yaml.org,2002 base:

I prefer a more generic name like 'yaml' or 'meta' for the top level info. 'directive' is a noun that usually describes single line syntax things like '#include'. I also don't like using plural, which is a foreign concept to many languages, when singular conveys the same meaning.

I'm guessing that zero or one !!yaml documents at the beginning of a stream is all that is needed in practice. Something like:

https://gist.github.com/ingydotnet/c5e17136d85c30e32b14

Cheers, Ingy