$schema about understanding-json-schema

[mdboom]

You may be correct, but it's actually a bit ambiguous from the spec itself. I may ask a question upstream for clarification.

[embray]

Hah! Yes, that should be clarified in the spec--$schema should always be allowed.

[MarkCatherall]

That would be great, thanks very much. FYI, Microsoft Visual Studio have interpreted it the same way as me (or rather the other way around!).

[embray]

I think @MarkCatherall is right here. When writing a schema, having $schema point to a metaschema does indicate that the document is a schema. But in a general document the presence of $schema does not mean that the document itself is a schema. So that text should probably be updated.

[MarkCatherall]

Thanks @embray. FYI, I'm also having this discussion on the json-schema repo, here: json-schema/json-schema#220 (comment)

More specifically about a corollary of the interpretation: you have to define $schema as a property in order to know what to validate it against, but that schema might not allow the $schema property!

[embray]

I'm surprised that this issue doesn't quote what the JSON Schema core specification says about $schema, so here it is:

6.  The "$schema" keyword

6.1.  Purpose

The "$schema" keyword is both used as a JSON Schema version identifier and the location of a resource which is itself a JSON Schema, which describes any schema written for this particular version.

This keyword MUST be located at the root of a JSON Schema. The value of this keyword MUST be a URI [RFC3986] and a valid JSON Reference [json‑reference]; this URI MUST be both absolute and normalized. The resource located at this URI MUST successfully describe itself. It is RECOMMENDED that schema authors include this keyword in their schemas.

The following values are predefined:

http://json-schema.org/schema#
JSON Schema written against the current version of the specification.
http://json-schema.org/hyper-schema#
JSON Schema written against the current version of the specification.
http://json-schema.org/draft-04/schema#
JSON Schema written against this version.
http://json-schema.org/draft-04/hyper-schema#
JSON Schema hyperschema written against this version.
http://json-schema.org/draft-03/schema#
JSON Schema written against JSON Schema, draft v3 [json‑schema‑03].
http://json-schema.org/draft-03/hyper-schema#
JSON Schema hyperschema written against JSON Schema, draft v3 [json‑schema‑03].

6.2.  Customization

When extending JSON Schema with custom keywords, schema authors SHOULD define a custom URI for "$schema". This custom URI MUST NOT be one of the predefined values.

All the text in this description indicates that the $schema property is only intended to be used in schemas. I agree with your original assertion that it does not not necessarily indicate that the document is a JSON schema unless its value happens to be one of the URIs listed above. It could hypothetically appear in some document where the $schema property happens to be used, but has some other meaning.

However, as you pointed out, Intellisense is interpreting it to mean that it indicates the JSON schema of any document. This is probably wrong as none of the above text indicates that it can be used that way. But also agree with you that Intellisense's behavior here makes an awful lot of sense, and that the use of $schema should be scale-invariant, as you put it :) (Are you a physicist by any chance?)

[MarkCatherall]

Hi Erik, good work quoting the actual source of this contention! I agree with you completely - the spec talks about it as if it were only for use in a schema, but doesn't seem to explicitly exclude its use elsewhere. I'm also with you on the practical point: use of the keyword in any json document might not be what the spec intends, but the world would be a better place if the spec did intend it!

I'm not quite a physicist; I like to think of myself as a "classically-trained engineer"!

[robbie-mac]

@embray
I disagree, the spec doesn't say that it is ONLY for schemas. It doesn't even say that a schema HAS to have it, it just RECOMMENDS it. It does state that when a schema does, it MUST be at the root, and that it MUST be a URI and a valid JSON reference.
It doesn't even say that it can ONLY be at the root.
@MarkCatherall
I don't this the spec talks as if it were only to be used in a schema. Just HOW it is used when writing a schema, and how it affects validation. EVERYTHING else is out of scope to this spec.

Consider this:
You write a schema, the intent of which is to describe data that will be used as a library catalog of schemas. Would you not include a url to that schema in the catalog? If so, why not use the $schema field. the result of which, your data might look like this:

[
    {"title": "JSON Schema Core",
     "$schema": "http://json-schema.org/draft-04/hyper-schema#",
    },
    {"title": "JSON Hyper-Schema",
     "$schema": "http://json-schema.org/draft-04/schema#",
]

If the spec said you could ONLY use the $schema field in a schema, then this data would not pass validation, and you couldn't write a schema that it could pass.
The result would be creating this data would be more involved.
In JavaScript/ECMAScript, if we had an array of schema in memory, we could simply copy values into a new object using filter, and voila, we have our data.
If we couldn't use the $schema tag, the code would become a forEach loop, and we would have to create variables and then move data from the schema object into the new variables. MASS HYSTERIA WOULD ENSUE!! ;)
I think that this is a brilliantly written spec. Could it be better? Sure. In this case, I think the ambiguity only exists if you try to expand the scope of the spec to include data. When reading the spec, don't assume intent if intent is not given. That will lead to creating phantom rules in your head that other might not make. Read the spec, for what it contains and no more.

[robbie-mac]

@embray

Hah! Yes, that should be clarified in the spec--$schema should always be allowed.

It is always allowed, by default. The only time its not allowed is when the schema author says it isn't. Do you really want to take that option away?
Hypothetically:
If I want an object to contain coordinates, no more no less, I write a schema that shows this. If we agree with you then somebody could put a $schema field in the data and it would still pass validation. Its completely irrelevant data, useless in my intent. If I was streaming this data over the internet from a mobile phone, that's a big waste of bandwidth.
When this spec was written, my hypothetical intend didn't exist. I think the spec authors considered that they couldnt cover all use cases, and included choice in the spec. The spec gives the author who is writing their own schema the ability to decide what is and what isn't acceptable in their data.

[embray]

I disagree, the spec doesn't say that it is ONLY for schemas. It doesn't even say that a schema HAS to have it, it just RECOMMENDS it. It does state that when a schema does, it MUST be at the root, and that it MUST be a URI and a valid JSON reference.
It doesn't even say that it can ONLY be at the root.

No disagreement there. The problem is that it's ambiguous and doesn't give any prescription for how $schema should be interpreted in any other context.

[embray]

@robbie-mac Following up on the rest of your comment, I agree that no further interpretation should be implied by the spec beyond what's written.

Of course you shouldn't necessarily want to require a $schema property in data (it's not recommended in schemas--which themselves are data--but only recommended).

However, we think that it's useful to allow such a specialized property in data as well, and have the same meaning as it has in a schema. However a schema for that data has to either explicitly allow a $schema property at the top-level of the data.

I see your point though about the JSON Schema spec not wanting to make any prescriptions about what goes into non-schema data. Perhaps a sister spec along the lines of JSON Reference could make such a prescription though.

[robbie-mac]

@embray
I totally agree that $schema should be allowed at the data level, but the meaning of such data can only be defined by, and interpreted by the application that is intended to process it. In the case of how it pertains to creating and validating a schema, the definition of $schema is pretty concrete. But beyond that it is really an adjective out of context. Unless, like the schema-core itself, every schema is required to have a human readable document defining the meaning of each property.
Personally, I do this anyways, just like code it needs to be commented, but unfortunately json doesnt allow comments... and rightly so.

This may sound like semantics but, Im note sure a sister spec is warrented, spec infer's a little to much authority for the purpose. Maybe a "Best practices" or even a "WIKI" style living document that contains pitfalls and advice on when to do things and when not to.

[handrews]

@MarkCatherall @embray @robbie-mac hi there, I'm popping in from the (revived) JSON Schema project.

A schema is identified as a schema by giving it the media type application/schema+json. In a context where media types are not identified, there is no inherent mechanism. "Because the user said so" is sufficient, really. It's totally reasonable, IMHO, for a tool to enable JSON Schema functionality based on $schema being present in the root object, but that is outside the scope of the spec entirely.

As for data (instance) files, a fundamental principle of JSON Schema is that it works without imposing any constraints at all on JSON documents. So data files can have $schema in them. And it can mean the same thing it means in application/schema+json or it can mean something totally different or contradictory. Associating an instance document with its schema is done outside of the instance document itself (with hyperlinks, media type parameters, or again "because the user said so").

I can try to write up a PR to sort this out (for draft-04, separate from updating the document for more recent drafts).

[embray]

@handrews With apologies with the high response delay, a PR to this effect would certainly be welcome. My understanding is that the mere presence of a $schema property obviously, in my mind, does not automatically imply that the document is a schema. However, when the document happens to be interpreted as a schema, as determined by context, then $schema has a meaning just as with any other property in a schema.

[handrews]

@embray no worries, I'm in no position to throw stones on response times. Sometimes it's instant, sometimes I forget entirely :-P

Your understanding is correct, assuming the "meaning" you're talking about is the meaning defined in the core spec. The context (including but not limited to the media type in a hypermedia environment) determines whether something is a schema, and if so, all schema keywords have the appropriate meaning (with$schema and id being defined in draft-04's core, by draft-07 core defines $schema, $id, $ref, and $comment, and all other keywords being determined by the meta-schema referenced in $schema)

[jdesrosiers]

This has been corrected in #147