Include how schema inclusion and schema reference works in a multi location/files context

[LasneF]

Reason/Context

• Why we need this improvement?

in corporate usage , Json Schema might not be self contained ; but due to reusability usually we get a common schema vocabulary in a dedicated files and then specifics domains vocabulary that is leveraging this common model

basics can be Address , currency , amount and so on in common , then having domain schema like a customer , a producer, a bill , pointing to various fields or object in the "common" pool . can be at field level or at object level

• How will this change help?

have a better understanding , and extended understanding about how referencing works

Description

Please try answering few of those questions

introduce a simple example with 1 file having for instance address model , and another exemple pointing on it

could be in this section about referencing a data schema
https://json-schema.org/learn/miscellaneous-examples

[jdesrosiers]

Is this what you're looking for? https://json-schema.org/understanding-json-schema/structuring

[LasneF]

kind of , yes but with even more straight forward sample .
My use case , that is quite common is to have json schema stored in a file system usually in git , that is cloned and so on
So need to leverage relative path , usually they do not have

looking on the getting started , this is leveraging $ref but with complete URL that is (for me) not so common

as well even in the documentation (https://json-schema.org/understanding-json-schema/structuring)
the use case of leveraging file system is not mentionned

looking here
"shipping_address": { "$ref": "/schemas/address" },

wondering if this should not be or can be rathe $ref : ./address.json $ref:/address.json

so mentionning given 2 files called Billing.json and Adress.json how to properly do the job

also a common use case beeing
given a file containing several schema call commonSchema.json (for instance containning basic field constrains like currency , various enums etc
how to reveference them (ie leveraging $ref with external file + $def

lastly i wonder if documenting legacy draft inside the main doc is not confusing rather, and over complexify the documentation

[jdesrosiers]

kind of , yes but with even more straight forward sample .

Agreed. It would be nice to have some more use-case oriented examples somewhere. However, what you're looking for is probably going to be implementation specific, so what you're looking for would be in the documentation of the library you're using. (I'll explain further in the next part of my response.)

My use case , that is quite common is to have json schema stored in a file system usually in git , that is cloned and so on
So need to leverage relative path , usually they do not have

I have two answers for you. I'll start with the standard approach and then I'll tell you what I'd do. JSON Schema isn't expected to know anything about files or the network. You're expected to load your schemas into the validator with a URI that identifies the schema. When the schema is evaluated, any references are retrieved from the schemas you loaded using the URIs you loaded them with. How you load schema is implementation specific, but I'll give an example using some psudocode.

./customer.schema.json

{
  "$id": "https://example.com/customer",
  "type": "object",
  "properties": {
    "address": { "$ref": "/address" },
    ...
  }
  ...
}

./address.schema.json

{
  "$id": "https://example.com/address",
  ...
}

const jsonSchema = new JsonSchema();

const customerSchema = readFile("./customer.schema.json");
const addressSchema = readFile("./address.schema.json");

jsonSchema.loadSchema(addressSchema); // The URI https://example.com/address is now associated with the address schema

const customer = { ... }; // Some customer representation
jsonSchema.validate(customerSchema, customer); // Validate the customer against the customer schema

The customer schema has the URI https://example.com/customer, so the address reference resolves to https://example.com/address, which the implementation understands because it was previously loaded. This way the schema can be evaluated without any knowledge of the file system or needing to know anything about the file system.

However, having to give schemas arbitrary URIs and having to manually load them from files in your code is not ideal and can get especially tedious if you have a large corpus of schemas. So, what I prefer (and what you clearly expect) is to use schemas directly from the file system and use relative URIs to reference them. Most implementations don't support this kind of use, but I wish more did. Here's an example.

./customer.schema.json

{
  "type": "object",
  "properties": {
    "address": { "$ref": "./address.schema.json" },
    ...
  }
  ...
}

./address.schema.json

{
  ...
}

const jsonSchema = new JsonSchema();

const customer = { ... }; // Some customer representation
jsonSchema.validate("./customer.schema.json", customer); // Validate the customer against the customer schema

Obviously, this is much simpler. Notice that there are no $ids in this version. When using schemas from the file system, the schemas are identified by their location and don't need arbitrary identifiers. You could give them identifiers that correspond to their location on the file system (file:///path/to/customer.schema.json), but that's both unnecessary and a bad idea because they would be coupled to a specific filesystem. Notice that the address reference is now a relative path to the file on the file system expressed as a relative URI.

In this version, we don't give the implementation a schema, we give it a relative path to file. The implementation does the work of reading the schema from the file system and is able to read the address schema as well because it's a relative reference from the customer schema file it appears in. I think this is a better approach than the way you're expected to use JSON Schema, but you might have a hard time finding an implementation that supports this way of working with schemas.

[LasneF]

thanks @jdesrosiers for the detailed answer ; I am exactly doing the second way , i think it s a common practice ,
this introduces the $ref with ./myFile.json (ie relative + file path that is more common than having schema hosted i guess)

It would be usefull to be mentionned somewhere in clear text in the doc (concept of uri beeing a concept not always clear :) )

thanks again!
you are the boss , let you close the ticket or keep it open till doc is updated

[jdesrosiers]

I 100% agree that working with files is by far the most common thing and more implementations should support that usage, but I want to point out that using http(s): URIs in JSON Schema doesn't mean the schema is hosted anywhere or that there is any expectation that the schemas are hosted at that location. Notice that the first approach I described involved no HTTP requests. The schemas are retrieved only from what you loaded manually. Implementations aren't expected to try to retrieve schemas from the network (although many do have that capability). The URIs are only expected to be used only to internally map to the schemas you loaded manually.

[jdesrosiers]

I'm leaving this open. I don't know if this content will fit into website document given JSON Schema's current philosophy on schema resolution, but I would like to at least write a blog post about this at some point.