Describe what could be at the other end of a $vocabulary URI

[karenetheridge]

The URI used to represent the vocabulary (in the $vocabulary keyword) SHOULD resolve to a document (not a schema, but any sort of plain text document that describes the vocabulary - ranging from a freeform README right up to a formal specification), that need not be publicly be resolvable, but SHOULD be resolvable in the context where it is intended to be used -- for example, if a company develops a vocabulary for its private use, then the vocabulary URI need not be publicly available, but SHOULD be available on its own private network as a description of that vocabulary. Note "SHOULD" not "MUST" -- this is just a recommended best practice but there may be reasons why it can't be done in all circumstances.

This also serves to clarify that the vocabulary URIs are NOT necessarily metaschemas themselves (which was raised as a question in an earlier issue).

At the locations of the draft vocabularies that we publish ourselves (e.g. https://json-schema.org/draft/2020-12/vocab/core), we could create short documents that summarized the intent of the vocabulary and linked back to the spec document that formally describes them.

[handrews]

Since I don't remember who was around when this was last discussed (and plenty of people who will see this probably weren't there!), I'll note that the plan was to wait for enough feedback from implementors and then spec out a machine-readable vocabulary description file.

While I don't have strong feelings about the path from here to there, I would object to anything that makes it harder for us to reach that goal. For the last two drafts we decided that having nothing was better than having something that would set expectations which we would then break.

[handrews]

Note that #602 was a partial start in this direction.

[karenetheridge]

ok.

Would it be appropriate to move this entire subject to a discussion instead of an issue, since it's so open-ended and there are a lot of ideas to explore?

[jdesrosiers]

I don't see why the vocabulary URI couldn't serve both human readable docs and a machine readable description. That's what content negotiation is for. Accept: text/html could provide human readable docs while Accept: application/schema+json could return a machine readable description. (Assuming the machine readable description is a schema dialect of some kind. Otherwise some other content type could be used)

[Relequestual]

Would it be appropriate to move this entire subject to a discussion instead of an issue, since it's so open-ended and there are a lot of ideas to explore? - @karenetheridge

Yes, I think so. I haven't yet enabled Discussions across all our repo. Once done, I'll convert this into a discussion (Unless you would specifically not want that for some reason)

[gregsdennis]

It seems I reraised this topic, not having seen this issue. ☝️

I'll leave the issue open as it will be good to have for a PR to reference.