First, this seems to view the URLs as primary. They aren't. The document formats are the most important part, even if you are doing a http-rpc style, not-really-REST interface.
Second, YAML? Haven't we already learned that markup languages don't make good programming languages? (That's what this is, right? Nobody is really going to use it to document an API, any more than anyone uses WSDL for more than generating stubs.)
Third (and not really germane), JSON schemas? Describing the format of JSON documents, in JSON? Because XML schemas are so wonderful?
Second, YAML? Haven't we already learned that markup languages don't make good programming languages? (That's what this is, right? Nobody is really going to use it to document an API, any more than anyone uses WSDL for more than generating stubs.)
Third (and not really germane), JSON schemas? Describing the format of JSON documents, in JSON? Because XML schemas are so wonderful?