Thank you Mattt, that's very helpful.
I also found a better validator, which checks key names as well as basic structure: Schema Markup Testing Tool | Google Search Central | Google Developers
I'm genuinely really torn on the issue of whether following this schema is the best way to approach this problem.
Fundamentally it seems like a good idea, and I do not particularly want to make a new standard, but the huge number of keys and flexibility in this spec does have drawbacks.
It’s easy to look at a spec like this and say that it’s the right decision because it’s a standard, and it supports every possible piece of metadata that might ever be needed. However, we should not underestimate the problems both package authors will have getting this data correct, and the problems tools (like the Swift Package Index) will have picking which of the fields to pay attention to.
For example, do we use name when we report on a Person listed as the author, or some combination of givenName, familyName, additionalName, or middleName? All are valid. The schema is so huge, and so much more than is needed that it feels like it’s going to make both filling it in, and sensibly parsing it really difficult.
There is also the significant issue of JSON being quite difficult for humans to read and write. The lack of support for comments, the poor readability/writability of multiline strings. At least initially, this file is going to be manually created by humans, and the scope for getting it wrong is huge. If it’s too hard to fill in, and the benefits are not clear, package authors won’t bother filling it in.
If we do go down the path of using this schema, I think the approach I'll take on the SPI site is to make a documentation page explicitly which subset of the spec we'll pay attention to, and give examples. There’s a chance that a subset of this spec may become well adopted, and at that point if people want to add more data into their metadata files, that’s OK.
I look at this schema, and then think back to what I was imagining this would be - a fairly simple YAML file with just a few, focused keys. It just feels so much more user friendly and so much less error prone.
I’m genuinely torn on the issue.