JSON pointer usage is not explained properly in core

[epoberezkin]

I may be missing something, but all I could find is:

https://github.com/json-schema-org/json-schema-spec/blob/master/jsonschema-core.xml#L316
https://github.com/json-schema-org/json-schema-spec/blob/master/jsonschema-core.xml#L410

There seems to be nothing about:

• the fact that JSON pointers should be in hash-fragments
• them being URI-encoded

There are only some examples to suggest 1 and nothing to suggest 2...

Please do not publish it in such shape

@awwright @handrews @Relequestual

[epoberezkin]

I think the problem here is that draft-04 is relying on JSON reference draft (https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) so it was not necessary to explain the syntax and semantics of $ref in the core.

From all the discussions here it followed that the decision was to essentially include JSON reference in JSON schema, but it didn't happen. The reference to JSON reference was also lost. So now whoever reads the spec would have no way to understand the syntax and semantics of $ref unless they look in draft-04... /sigh

[handrews]

@epoberezkin I have a change that I nearly finished a while ago to add the fragment syntax to the IANA media type declaration. I'll tidy that up and post it.

We do not need to explain how to URI-encode JSON Pointers for fragments, as the JSON Pointer RFC already mandates that behavior. We just reference the RFC.

[awwright]

@epoberezkin Fragment handling is defined by the semantics of the media type. Of course, that means we need to define it for application/schema+json. I sort of thought application/json did this, but it turns out there's no such registration.

I don't think this is a roadblock, but it does need to happen before media type registration with the IANA.

[epoberezkin]

@awwright @handrews thank you for hte answer.

Fragment handling is defined by the semantics media type.
I have a change that I nearly finished a while ago to add the fragment syntax to the IANA media type declaration.

It is a bit over my head (and probably a couple of other heads too)... In any case just saying something about it in the spec with the link(s) to the relevant document(s) or whatever would point people in the right direction rather than leaving them guessing what it is about and how it is connected.

Without some clarification I think there will be many other people who won't be able to join the dots in the same way I can't.

[handrews]

I've made a first pass at the proper fragment definition. I tried to follow all the best practices I could fine but it's probably not perfect. I think as long as it's not egregiously wrong we should accept it and refine it further in the next draft.

I included a note to us about some of the more confusing situations. We do not have time to debate all options before Draft 06, this acknowledges the strange corners and indicates that we intend
to address them somehow.

The one point (other than correcting actual errors) that I would be willing to reconsider for Draft 06 is what restrictions to put on plain name fragids (the local names).

• Anything that doesn't conflict with JSON Pointers (what I put in now)
• XML rules (what was there before, although we don't need to tell people that fragment URI references start with "#")
• HTML5 rules (at least one character and no spaces)

[epoberezkin]

@handrews I'll need to read the PR attentively but it looks much better and it also looks like it may address $id issue as well.

What I don't understand, is why we need to separately describe "naming subschemas in a JSON Schema" with $id that are only hash fragments while these fragments are still URI references? Isn't it the case where we provide what you call "tutorial" how to do things when it's already covered by "URI reference" definition?

That's exactly what confused me in $id section - either it restricts what $id in subschemas can be (which was not the intention) or it provides a specific recipe for using references (which is what both you and @awwright argue against in all cases, and I agree with that).

I hope you can understand what I am trying to say here, sorry for any inaccuracies in terminology.

[handrew]

probably want @handrews instead

[handrews]

@epoberezkin yeah, I understand that it is weird- I think the PR is more clear but some of this has to do with best practices for fragids. In particular:

Plain names are a common type of fragid structure. A plain name fragid is a fragid that is used to identify a named structure within a document, such as one identified by an @id attribute in HTML, a @xml:id attribute in XML or the name of a function within a Python program. These fragids are opaque to processors

and

If the media type includes structures that can be given local names or identifiers, plain name fragids should be reserved for addressing those structures.

So this means that we need to explain the mechanism for naming structures and indicate that it correlates with plain name fragments. So it needs to be called out somehow. I tried to reduce it to "name things with fragment-only URI references" because that's the most concise way to do it.

Really, this is a side-effect of conflating two functions in the "$id" keyword: changing base (I know you hate it, but a lot of us see the need for it) and naming structures (subschemas) within the document. You might recall that I tried to split them in PR #155. That did not go over well. I was ultimately convinced by @awwright's assertion that the trend is to combine these things. But it does produce weird cases.

[epoberezkin]

So this means that we need to explain the mechanism for naming structures and indicate that it correlates with plain name fragments. So it needs to be called out somehow. I tried to reduce it to "name things with fragment-only URI references" because that's the most concise way to do it.

@handrews I still don't understand why we need it as part of the spec. Functionality-wise nothing has changed, these name fragments are supported in draft-04 because they are just URI and they also change base URI (by appending or replacing the current hash fragment). So why do we need to describe them separately?

[epoberezkin]

Can be closed once PR #245 is merged