Are schemas loaded via $ref added to any working namespaces?

[JC3]

Consider the following two schema documents:

Document 1: Retrieval URI irrelevant:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "xri://+this.discussion/schema1",
    "title": "Example Schema 1",
    "properties": {
        "someProperty": {
            "$ref": "file:///path/to/local-schema.json#/$defs/def1"
        }
    }    
}

Document 2: Local filesystem at /path/to/local-schema.json:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "xri://+this.discussion/schema2",
    "title": "Example Schema 2",
    "$defs": {
        "def1": {
            "somekeyword": "somevalue",
            "def1b": { "somekeyword": "somevalue" }
        },
        "def2": { "somekeyword": "somevalue" }
    }
}

Now, make the following assumptions about an application that is processing schemas:

1. Document 1 is the document of interest, and also the only specific document that the application "understands ahead of time".
2. The application implements a policy of treating missing reference URIs as URLs and attempting to retrieve them; note that this is a JSON Schema spec-compliant behavior.

So, when processing document 1, the application sees the reference to file:///path/to/local-schema.json#/$defs/def1, notes that it is not an already-known identifier and so treats it as a URL, retrieves document 2, resolves the fragment, all is well.

However, my question is: upon retrieving document 2, should document 2 now exist in the space of schemas that the application is aware of (...even if only in some sort of limited scope)?

For example, if document 1 were, instead, the following:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "xri://+this.discussion/schema1",
    "title": "Example Schema 1",
    "properties": {
        "someProperty": {
            "$ref": "file:///path/to/local-schema.json#/$defs/def1",
            "newSubkey1": { "$ref": "schema2#/$defs/def1" },
            "newSubkey1b": { "$ref": "schema2#/$defs/def1/def1b" },
            "newSubkey2": { "$ref": "schema2#/$defs/def2" }
        },
        "newProperty1": { "$ref": "schema2#/$defs/def1" },
        "newProperty1b": { "$ref": "schema2#/$defs/def1/def1b" },
        "newProperty2": { "$ref": "schema2#/$defs/def2" }
    }    
}

Should any of those other reference work? They would all resolve to the absolute URI xri://+this.discussion/schema2 with fragments, which matches document 2.

I have follow up questions that depend on whatever the answer is here, I'll leave them out for now.

[karenetheridge]

Should any of those other reference work? They would all resolve to the absolute URI xri://+this.discussion/schema2 with fragments, which matches document 2.

It depends on which of the $ref or properties keywords are evaluated first. schema2 (and the $id it defines) aren't known to the evaluator until the document referenced by $ref is loaded and parsed.

Therefore, the evaluation result depends on keyword execution order, which is not well-defined by the specification.

The only exceptions to the indeterminate ordering are not well-stated in the spec, but are implicit from property definitions:

• $schema must be evaluated first, because its result will affect all the evaluation semantics (that is, the dialect is determined here);
• $id must be evaluated next, as it determines the base URI for future $ref and $dynamicRef evaluations, as well as the base URI used for in absoluteKeywordLocation in all errors and annotations;
• the unevaluated* keywords must be evaluated after the applicator keywords that produce annotations that they consume.

IMO the spec should clearly state that all of the core vocabulary keywords MUST be evaluated first before all other vocabularies, and then the $ref ambiguity described by this thread will be resolved.

[JC3]

Thanks. Confirming a point: When you say it depends on the evaluation order, that implies that the answer at least isn't "no" -- i.e. evaluation order aside, schema documents loaded by $ref should (at some unspecified point) get added to the set of known schemas and stay there for the remainder of the evaluation process. Is there anything in the current draft that implies that this should happen at all, or is it completely unspecified?

[JC3]

(Btw, re: your last sentence; should probably also make it clear that core keywords in all subschemas would have to be evaluated before other keywords in the roots [or not, but at least some specific defined behavior is needed] -- for example, consider the modified document 1 but with "someProperty" placed after its sibling "newPropertyX" keys [a case I missed when building that example].)

[karenetheridge]

The schema whose $id is the resolved result of the $ref must be "known" to the evaluator at the time of the $ref evaluation, or the evaluation will fail (not with an "invalid" result, but a "neither valid nor invalid, but rather an error" type of result). Whether the implementation chooses to load that resource at runtime (for example by fetching a file from disk or a document from the internet) is at the implementation's discretion -- it is not required to support just-in-time document loading:

https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.3

he resolved URI produced by these keywords [$ref, $dynamicRef] is not necessarily a network locator, only an identifier. A schema need not be downloadable from the address if it is a network-addressable URL, and implementations SHOULD NOT assume they should perform a network operation when they encounter a network-addressable URI.

[JC3]

Sure; but if the application chooses to load the resource at runtime, then any additional ids defined in that resource necessarily can't be known ahead of time. So it seems like while the spec leaves that behavior up to the application, the application's choice (which theoretically shouldn't affect the outcome, otherwise the spec shouldn't leave it application-defined) becomes important: If it fetches at runtime then it must necessarily resolve subschemas depth-first or do some other sort of multi-pass evaluation, and if it fetches ahead of time then it won't be able to handle ids defined in referenced documents unless it actually evaluates all those references while doing the ahead-of-time fetch (so it can get all dependencies), which creates a bit of a paradox. Especially if the document it is referencing is outside of the application's control e.g. defined by a third-party.

[handrews]

@JC3

Should any of those other reference work?

Generally speaking, regardless of how you loaded a schema resource, it should be available under its $id. Whether or not it is also available by its retrieval URL is definitely not covered by JSON Schema, nor do I think it particularly needs to be. Referencing by $id is the correct approach and is much more predictable than retrieval URIs.

I would strongly advise against mixing addressing modes like this. It's the mixing that introduces a dependency on the keyword order. If you use consistent addressing, it doesn't matter which is resolved first. Even if there was a defined ordering, it does not seem like a good idea to rely on it to establish an alternate addressing approach. You could easily break things by a fairly benign-seeming schema change.

If you want to load schemas from disk, do that up front. If you're writing an implementation, one strategy I've seen is registering handlers for URI resolution, which would (for example) allow you to intercept a URI and convert it to a local filesystem path during testing, but do a network retrieval in production.

I would say it's a "best practice" to separate the identification and location of schemas. Identification needs to remain stable, but location might change depending on the environment. You don't want to have to edit your schemas for that.

[handrews]

When a $ref is resolved, does the referenced document become part of the evaluator's general scope (as if it were pre-loaded)

We should probably be more explicit about this in the spec, but yes, that's my expectation.

[JC3]

When a $ref is resolved, does the referenced document become part of the evaluator's general scope (as if it were pre-loaded)

We should probably be more explicit about this in the spec, but yes, that's my expectation.

Thanks. Then, back to evaluation order (in a sense); if document C were modified to this (the order of the two properties has been swapped):

{
    "$id": "xri://+random.application/schemas/data",
    "properties": {
        "spareTDA": {
              "$comment": "user may specify a spare transdimensional ambiguator, if necessary",
              "$ref": "https://important.org/components/transdimensional/ambiguator.schema.json"
        },
        "device": { "$ref": "https://important.org/complicated-device.schema.json" }
    }
}

Should that also be expected to work?

Note that RFC7159 defines JSON objects as "an unordered collection" (that is, the modified document C above is technically equivalent to the original document C). It also notes that "JSON parsing libraries have been observed to differ as to whether or not they make the ordering of object members visible to calling software" i.e. it may not actually be possible in practice for a given JSON Schema evaluator to be aware of the ordering of keys in the documents at all.

Also note that there is no distinguishing difference between /properties/device/$ref and /properties/spareTDA/$ref that would allow the JSON Schema spec to concretely define the order in which they are evaluated, other than their names and the referenced URIs.

---

PS:

you did not explicitly specify if encabulator.schema.json is accessible by treating its $id as a URL, but since you gave it that URL as its retrieval URL I assume that it is indeed accessible.

Your assumption is correct; sorry about not explicitly mentioning that!

[handrews]

@JC3 if you are relying on performing a network operation whenever you encounter $ref, then no, that is not guaranteed to work.

Basically, it's ill-advised to rely on network operations during processing. But it's not just that: in the previous example, there's nothing that forces you to process $defs and notice the embedded resource prior to needing it.

Section 9 on loading schemas is not as clear as I'd like it to be, in part because there's not consensus on how schemas ought to be loaded. In my view, loading, which includes scanning the lexical scopes for schemas and noting their URIs, is a separate process that happens before validation. While it's possible to try to find schemas on-demand, it's a lot more complex to do so, and the spec does not require handling all of the possible cases that you might come across. Your latest example pretty much explains why: it's not necessarily possible to figure out how to locate all of the schemas.

Typically what I see is people loading all of the schemas up front, and then using them.

[JC3]

But it's not just that: in the previous example, there's nothing that forces you to process $defs and notice the embedded resource prior to needing it.

I see; that was a big component in my question; whether or not other embedded resources in the referenced document were put in play when a reference to some subschema in that document was resolved.

I'm a little confused now though, so just to confirm, this is no longer the answer:

When a $ref is resolved, does the referenced document become part of the evaluator's general scope (as if it were pre-loaded)

We should probably be more explicit about this in the spec, but yes, that's my expectation.

And instead it's:

@JC3 if you are relying on performing a network operation whenever you encounter $ref, then no, that is not guaranteed to work.

Correct?

Note that the assumption here is that all retrieval operations that can succeed, will succeed... that is, the topic is the JSON Schema spec rather than, say, the reliability of networks (or the user's hard drive crashing for file URLs, or the user's mail server being down for cid URLs, or cosmic rays corrupting RAM with random bit flips at just the wrong time, or the possibility of a meteor destroying half the planet just when a $ref is about to be resolved, etc...).

---

Typically what I see is people loading all of the schemas up front, and then using them.

In my last example, let's go back in time a little to just before important.org's infamous "heated usenet discussion", when /components/transdimensional/ambiguator.schema.json was an accessible document, via that URL.

Let's assume that the user is using that example application to validate an instance against document C. Can you give an example of:

• How important.org communicated the list of documents to preload to the application developer or user (your choice), and
• How that list is input to the application?

Now, with that in mind, go forward in time again. Important.org has now made a change to their file structure; ambiguator.schema.json is no longer network-accessible, and has been moved into encabulator.schema.json and given a location-independent $id. Can you give an example of:

• How the application developer (or user) is made aware that important.org changed their internal file structure, and
• How important.org communicates the new list to the application developer or user, and
• How the application developer or user proceeds to update the input to the application?

[handrews]

@JC3 sorry for dropping the ball on this, some Real Life Stuff™ came up and I'm still working through the subsequent backlog.

Note that the assumption here is that all retrieval operations that can succeed, will succeed... that is, the topic is the JSON Schema spec rather than, say, the reliability of networks (or the user's hard drive crashing for file URLs, or the user's mail server being down for cid URLs, or cosmic rays corrupting RAM with random bit flips at just the wrong time, or the possibility of a meteor destroying half the planet just when a $ref is about to be resolved, etc...).

The JSON Schema specification explicitly avoids requiring network operations during processing. The expectation is that schemas are pre-fetched and pre-loaded, and implementations hold on to them in some sort of URI-indexed storage. $ref is resolved against that. Some implementations offer network or other fetch capabilities, but that's additional functionality beyond what the spec requires.

Part 2 of the presentation I posted for discussion at #220 talks more about scanning for URIs within a schema (with diagrams), and how those should be available through the URI-indexed storage once the larger schema document is loaded.

All of those other things are application-specific. The exact interface to pre-load a schema is JSON Schema implementation-specific, but should be clearly documented for any given implementation. But there's no way JSON Schema can define a process for all of that other stuff that would be universally well-suited to all applications.