Inline schema

[fulldecent]

I am requesting that it be legal to inline a full JSON schema into a JSON document by including the schema itself as the value for the $schema key, rather than referencing an external file.

Why would anybody want to includ their data format specification in the same file as their data?

I don't know but, that is the current state of the art for:

• Excel XLS files
• Excel XLSX files
• OpenDocument ODS files
• Sequel database dumps
• Binary database dumps

Perhaps it sounds like a ridiculous suggestion, but actually this is how most people are currently accustomed to sending data files.

With inline schema, we can now ask everyone that is currently exporting XLS to also support JSON+Schema files. This saves them from having to worry about exporting a dataset that produces two files.

[handrews]

There's nothing currently stopping this- we (the JSON Schema project) cannot change regular JSON (the application/json media type). While you could not describe such a document-with-an-inlined-schema as application/schema+json, there's no reason that your application can't look for a $schema property and try to interpret its contents as a schema.

We do define application/schema-instance+json, part of the requirements for that are that it NOT specify any particular structure. It is intended to be fully compatible with application/json, just adding a media type parameter and URI fragment syntax. If you want to use a media type to denote this inline schema behavior, you can create your own custom media type for it.

Most validators don't care where the schema comes from, so grabbing it from a $schema key and passing it to the validator should be simple enough.

I might recommend something like $inlineSchema, though, to avoid confusion with $schema. While it is not part of JSON, many people do put a $schema URI in their data files and treat it like the JSON Schema $schema keyword.

[fulldecent]

Here are valid documents of the type application/json as defined by ECMA-404:

• []
• true
• [5,6,7]

None of them include a schema. Here are a bunch of JSON files including schema information:

• {"$schema":"http://...","key2":"value2}
• {"$schema":"http://...","bob":[1,2,3]}
• {"$schema":"http://...","steve":{"x":[]}}

Is there a more formal definition of "JSON files including schema information"? Is there a mime type?

That is where I am looking to open this issue. Currently, the convention (recognized by who?, documented where?) is that a $schema is a URL. I am looking to negotiate with the editors of that documented convention.

[handrews]

Is there a more formal definition of "JSON files including schema information"?

Nope.

Is there a mime type?

Nope, you could work on one and register it, though.

Currently, the convention (recognized by who?, documented where?) is that a $schema is a URL.

In JSON Schema (application/schema+json), this is not a convention, it is part of the specification. $schema is the URI of the schema that describes the schema, a.k.a. the meta-schema. I do not see any reason to change that behavior. There are generally only a few meta-schemas, and including them inline in every document would be a huge amount of overhead. You just want to load them once and recognize them by URI every subsequent time that you need them.

In non-schema JSON files, some people seem to use $schema to indicate the URI of the schema describing the contents of the file. This is fine, but not part of JSON Schema. We do not particularly recommend or forbid it, or really care one way or the other at all.

I would recommend against using a property name that is a JSON Schema keyword in a way that conflicts with its definition in JSON Schema, while also somehow related to JSON Schema, because that's incredibly confusing. I'm confused even writing that sentence. So if you want novel behavior, pick a new property name.

Any way you look at this, it is outside of the scope of the JSON Schema project. Anyone is welcome to define a media type that uses JSON Schema in some way, including ways not specified by the JSON Schema spec. See OpenAPI, or W3C WoT's "Thing Description" format, both of which embed JSON Schemas. Those are description formats which build on JSON Schema rather than formats that use the schema to describe the files themselves, but either way, the media type defines how it uses JSON Schema which is valid.

I believe the spacetelescope "Understanding JSON Schema" guide, which recently moved under this org (at https://github.com/json-schema-org/understanding-json-schema ) might give the $schema usage as a convention, if you want to go look at that. I would and will still argue against using $schema with anything other than a URI, but if you want to talk to the editors about putting in an alternate convention you could file an issue at that repo.

It is definitely not a part of the JSON Schema specification, which is what this repo is for, so I'm closing this here.

[fulldecent]

Got it, and thank you, understood loud and clear.