Suggestion to add explanation of logic behind character set choice for $anchor

[ssilverman]

This issue suggests that some sentences or a paragraph be added to the $anchor section in the core spec describing the logic behind the character set choice. It doesn't match the "fragment" production from URI, and it's not clear why because it functions similarly.

In my experience, it's often the case that explaining these things reduces the temptation to be more lenient with the spec.

See: 8.2.3. Defining location-independent identifiers with "$anchor"

[ssilverman]

I'll add: The current $anchor character set is [-A-Za-z0-9.:_] and the URI fragment character set is [-A-Za-z0-9._~!$&'()*+,;=:@/?]. It leaves out [~!$&'()*+,;=@/?].

[handrews]

The reference is in section 5, it's not desirable to duplicate every reference to every section that depends on it. I won't object to a PR with some minimal clarification here but the spec is already really long and if you want to know about fragments you should read the section on fragments.

[ssilverman]

I'm not finding any references in section 5 that talk about restricting a fragment's character set, including in the referenced RFCs and W3C documents. There's references to XML names and JSON pointers and fragments, etc.

Update: I'll add: I'm happy to create a PR with a small change, I'm just not sure where to reference because section 5 doesn't seem sufficient.

[handrews]

That's because not every single thing is laid out explicitly in the spec. There's a link to fragment best practices, which talks about what the point of plain name fragments is.

These are specs, not tutorials. Readers are expected to check references for context, have (or be willing to develop) a working knowledge of the relevant related specifications and the language used in them. The JSON Schema core spec is already way too long and in need of editing, with more things moved to supplemental materials.

We should perhaps have a conversation on slack about what does and does not go in the spec. I want the spec to be clear, and in that sense issues like this and #899 are helpful. But there are an endless number of obscure points involved in building a specification and it is not desirable to lay every single one out in the main text. That's why we have a web site. And in theory, a book (although the status of "Understanding JSON Schema" is a bit up in the air right now).

The point of the specification is so that someone can understand how to implement JSON Schema, and secondarily how to use it (but specs are rarely the easiest way to learn how to use anything, and the fact that the JSON Schema spec is arguably the best way to learn JSON Schema right now is not really a good thing).

I'm certainly not going to block a reasonably concise PR on this, but at the same time I'm concerned about a flood of elaborations of minor points. If anything, the spec should be more concise, but I'm not good at concise. As this comment demonstrates :)

[ssilverman]

I'll see if I can come up with a concise PR.

@handrews can you assign this to me? It looks like I'm not on this particular team.