Using $schema in JSON documents

[gregsdennis]

We've long held that although many editors support using $schema in JSON documents to indicate the schema to be used to validate that document, it's not something we can specify because we don't specify JSON. Therefore, we can't say that $schema with a URI value in a JSON document means it should be validated by the JSON Schema represented by that URI.

This makes sense, but what if we turn it around?

Instead we could say that when a JSON Schema implementation processes a JSON document that has $schema in it, that URI indicates the schema to use to validate it.

This changes a paradigm, at least for my implementation. Currently for many implementations, the schema needs to be provided explicitly: something similar to

schema.Validate(json);

or

Validate(schema, json);

With this requirement, a user could instead just do

Validate(json);

and the implementation would detect the schema to use.

I think this is probably the closest we could get to specifying the use of $schema in instances, which seems to be something that users want.

(There is also some overlap with json-schema-org/json-schema-spec#1420 in that the application/schema-instance+json media type could also be registered to accept a schema parameter that the implementation could honor.)

This also has the nice side effect that processing a schema by its meta-schema just becomes processing a schema as any other instance.

[jdesrosiers]

IMO the main argument against defining $schema as a special value in JSON documents is that it means you can't use $schema in a way other than the special meaning we define. One of the core principles of JSON Schema is that it allows you to describe any JSON document. You wouldn't be able to express a JSON document that has a $schema property because it would conflict with a $schema keyword with special meaning.

Another limitation of this approach is that it would only work for objects. JSON Schema can represent other types at the root as well and there would still need to be some way to externally associate a JSON document with its schema.

(There is also some overlap with json-schema-org/json-schema-spec#1420 in that the application/schema-instance+json media type could also be registered to accept a schema parameter that the implementation could honor.)

The application/schema-instance+json media type could be defined as a variation of JSON where $schema has special meaning. We could then define JSON Schema to describe that format rather then JSON. I don't think I'd want to do that, but that would solve the conflict.

I think I'd rather document it as a common convention rather than something that goes in the spec.

[nikiluk]

One possible reflection that I have that stands against specifying $schema in the JSON itself (and therefore this be implemented in prod environment) is that it opens a potential security hole where JSON docs will always "self-validate". One not being careful in specifying the exact schema for the JSON validator may have issue "by default"

[gregsdennis]

The meta-schema already self-validates.

But more than that, just respecing $schema in the instance isn't sufficient to self-validate. It would also have to respect $id. Then the "attack" (if you can call it that) would be to submit an instance that has both a $schema and an $id where they're the same URI.

[GabenGar]

This shouldn't be a concern of JSON Schema itself, as it normalizes a lot of cans of worms, such as async logic being a-okay for validation, implementations willy nilly doing HTTP requests just because of a field in a JSON file and a range of behaviours in case of failure states. You really don't want this mechanics outside of IDE helper tooltips.
It can get confusing for non-devs, as proliferation of this behaviour can make someone think specifying "$schema" in any JSON file will somehow enable magical tooltips as a default feature of JSON and not just the editor doing a pretty gnarly under the hood magic.

[tschmidtb51]

I stumbled across this discussion while looking for a clear answer whether $schema is allowed/prohibited/unspecified in JSON documents (IMHO it should be allowed, so that data can provide hints about the schema it promises to be valid for).

While reading through the discussion, I was wondering whether I missed something or whether the change in the interpretation would prevent to write meta-schemas that enforce a certain value for $schema:

Metaschema example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/metaschema.json",
  "type": "object",
  "required": ["$schema"],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://example.com/metaschema.json"
    }
  }
}

An arbitrary instance:

{
   "$schema": "https://example.com/metaschema.json",
   "$id": "https://example.com/some-schema.json",
   "type": "object",
   "properties": {
     "some-key": {
       "type": "string"
     }
   }
}

[jdesrosiers]

There has been no change in interpretation. It's always been the same. Your example works fine because the "arbitrary instance" in this case is a schema, which allows and understand $schema. It's when using that schema against an instance that's not a schema where using $schema is not standard. So, to extend your example of a schema referencing a meta-schema, this would be an instance referencing as schema.

{
   "$schema": "https://example.com/some-schema.json",
   "some-key": "foo"
}

This is what this discussion was about. It's supported by some editors like vscode, but it's not part of JSON Schema. It's just an editor feature.

[nikiluk]

The data file has no standard way to declare "I belong to this schema."

Sometimes the approach is:

{
  "$schema": "https://example.com/schemas/user.json",
  "name": "John"
}

it is commonly understood by editors such as VS Code and some JSON tooling ecosystems. Still not a standard.