Clarification on multi-file usage about jschon HOT 6 CLOSED

Hi,

Thanks for raising this issue - I'm working on improving the docs which are pretty scant in this area and will definitely add this as an example.

The add_schema method is actually not meant for application use - it's called internally during JSONSchema construction.

Okay, so let's say you have the following two schemas in a schemas directory (relative to the current working dir):

schemas/schema-org.json:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schema-org",
    "type": "object",
    "properties": {
        "people": {
            "type": "array",
            "items": {
                "$ref": "https://example.com/schema-person"
            }
        }
    }
}

schemas/schema-person.json:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schema-person",
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        }
    }
}

There are actually two ways to do this. In both ways you have to explicitly load your primary schema (the org schema in this case), and use that to evaluate the JSON data.

Option 1: Set up a base URI-to-directory mapping on the catalogue. In this case when the "$ref" to the person schema is encountered during the JSONSchema.loadf, the catalogue knows where to find that schema on disk, and loads it on the fly.

from jschon import create_catalogue, JSON, JSONSchema, URI

catalogue = create_catalogue('2020-12', default=True)
catalogue.add_directory(URI("https://example.com/"), 'schemas')

schema = JSONSchema.loadf('schemas/schema-org.json')
result = schema.evaluate(JSON({
    "people": [
        {"name": "Alice"},
        {"name": "Bob"}
    ]
}))
print(result.output('flag'))

Option 2: Load all of the schemas up front. In this case when the "$ref" is encountered, the target schema is found already cached in the catalogue.

from jschon import create_catalogue, JSON, JSONSchema

catalogue = create_catalogue('2020-12', default=True)

schema_person = JSONSchema.loadf('schemas/schema-person.json')
schema_org = JSONSchema.loadf('schemas/schema-org.json')
result = schema_org.evaluate(JSON({
    "people": [
        {"name": "Alice"},
        {"name": "Bob"}
    ]
}))
print(result.output('flag'))

In general, option 1 is probably better, because option 2 requires you to load the schemas in "$ref" dependency order.

Hope that helps!

from jschon.

Oh btw, I'm going to push out a long overdue release pretty soon, but in the meantime if you're using v0.6.0, just replace create_catalogue with Catalogue.create_default_catalogue.

from jschon.

In fact, there's a third way, which might be preferable even to option 1 above, since it avoids having to put the same directory path in two different places:

from jschon import create_catalogue, JSON, URI

catalogue = create_catalogue('2020-12', default=True)
catalogue.add_directory(URI("https://example.com/"), 'schemas')

schema = catalogue.get_schema(URI("https://example.com/schema-org"))
result = schema.evaluate(JSON({
    "people": [
        {"name": "Alice"},
        {"name": "Bob"}
    ]
}))
print(result.output('flag'))

from jschon.

Oh wow, what a rapid response :) Thanks I'll have a look at this as soon as I get back to my code!

from jschon.

That worked perfectly, thanks!
I still have some quirks of json-schema to learn, but being able to integrate it into our existing python tooling will be great.

from jschon.

Great, glad to hear that!

from jschon.