Describe intent of 9.2.1 Internal references

[reece]

Section 9.2.1 describes Internal references. It is unclear to me why these are useful. Please consider a one-sentence statement about utility. (Descriptions of utility and intent would be generally helpful throughout.)

9.2.1 says:

When an implementation then looks inside the <#/items> schema, it encounters the <#item> reference, and resolves this to http://example.net/root.json#item which is understood as the schema defined elsewhere in the same document.

If I read this correctly, internal references permit schemas to define a JSON pointer fragment to themselves rather than be accessed by JSON Pointer. For this example, is "$ref": "#item" equivalent to "$ref": "#/definitions/single"? If so, why is this useful?

[handrews]

There are really two questions that you're asking here: one about types of fragments, and one about "internal" reference. First the fragment topic:

"$id": "#item" defines a plain name fragment.

A subschema reference by a plain name fragment can be moved around within the schema file without needing to update references. Since JSON Pointers describe how to traverse the JSON document, if you move a subschema that's being referenced by a JSON Pointer fragment, your references will break.

Sometimes you want to reference by location (JSON Pointer fragment), and sometimes independent of location (plain name fragment). For instance, if you publish a schema that defines re-usable types, you probably don't want people who use your re-usable types to care how you structured your "definitions" section (e.g. a flat namespace, or with additional "definitions" nested in sub-schemas). So you'd define plain name fragments and document those as the way to reference the re-usable types.

On the other hand, JSON Pointers are great within a single file because they hint at where someone reading the file can find the subschema.

As far as why this section is about "internal" references, it's just saying that you don't have to construct an absolute URI and resolve it however you resolve external references. Your implementation can just keep track of reference targets as it loads the schema and resolve references that it recognizes as internal without looking anywhere else.

[handrews]

@reece if you've got a concise way to include key points from this discussion in the spec, we're definitely open to clarifying language. We just don't want to get too deep into use cases in the spec. Detailed use cases and usage guides belong on the website (the json-schema-org.github.io repository, so feel free to file an issue there if you would like to see a more in-depth treatment).

[reece]

@handrews Wow. Fabulous answer. I appreciate your clarity and thoroughness!

How about a one-sentence addition to 9.2.1 like the following?

"Internal referencing enables a subschema to be logically relocated within a schema without requiring that JSON Pointer references are updated."

[awwright]

Believe it or not, I actually didn't even consider that fragment identifiers let you move the schema around in a file.

Nonetheless, that's a pretty good benefit.

[handrews]

Fixed in #356.