This is a good critique, but there is nothing specific to YAML in it. For any data serialization format (XML, JSON, Avro, protobufs), a schema in a schema IDL

This is a good critique, but there is nothing specific to YAML in it. For any data serialization format (XML, JSON, Avro, protobufs), a schema in a schema IDL is a good idea and often required. However, the schema alone cannot tell you everything a user should know about the data. The thing I frequently see is systems where there is a source file in a schema IDL and one comment per field as the "documentation". This is something, but for most non-trivial data there are things that should be documented at a higher level than the field.