Explain why $id needs to allow really weird things

[handrews]

There are quite a few things that you can do with $id that would be ill-advised when writing schemas for human consumption, but that have clear applications in processing tools. People often complain about the complexity of $id for this reason, and suggest removing functionality (or removing it entirely). Explaining the use cases, and why they are important despite being rarely seen in human-authored schemas, would help people to understand the keyword better.

Here's an explanation of one of those use cases that I wrote in json-schema-org/json-schema-spec#349 (lightly edited to stand better on its own):

An $id such as bar#/definitions/bar is allowed, although probably confusing for human readers. I've seen it in tools that "dereference" schemas by replacing all $refs with the things to which they refer (this only works when there are no circular references). To make that work right, you need to preserve the $id of the schema when you replace $ref with it.

That often includes a JSON Pointer fragment, especially when that $ref target does not declare a plain-name fragment $id of its own. But I've only seen that done as a processing step to produce a single in-memory non-circular data structure, and not as something that is presented to a schema user directly.

[handrews]

This has been on hold in part so that we can resolve json-schema-org/json-schema-spec#514 and json-schema-org/json-schema-spec#523 first, as they will likely change the explanations and use cases a bit.

[handrews]

$id no longer allows the really weird things. Problem solved.