JSON Schema Identifiers

[watuwo]

I believe that URI/IRI handling in JSON Schema is underdefined.

First I present examples where implementations behave mutually inconsistently. I am doing this to show that the problem is of practical relevance.

The topic of this post is not "which implementation is correct". I believe that it is either impossible or unnecessarily hard to determine the correct behavior from the JSON Schema specification. I believe that with enough effort more similar examples could be found.

Example 1

Consider this schema:

{
  "$schema":"https://json-schema.org/draft/2020-12/schema",
  "$id":"http://example.com/test-001",
  "$ref":"http://example.com/foo%2Ejson",
  "$defs": {
    "abc": {
      "$id": "http://example.com/foo.json",
      "const": 1
    },
    "def": {
      "$id": "http://example.com/foo%2Ejson",
      "const": 2
    }
  }
}

Consider this instance: 1.

Let us try some implementations (all from here):

• These implementations report the instance as invalid:
  • hyperjump (online)
  • jschon (online)
• These implementations report the instance as valid:
  • json-everything (online)

The implementations do not behave consistently.

Example 2

Consider this schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "http://example.com/test-002",
  "allOf": [
    {"$ref": "#/$defs/a~1b"},
    {"$ref": "#%2F%24defs%2Fa%7E1b"}
  ],
  "$defs": {
    "a/b": {"const": 1}
  }
}

Consider this instance: 1.

Let us try some implementations (all from here):

• These implementations report the instance as valid:

  • hyperjump (online)
  • json-everything (online)
  • jschon (online)

• These implementations reject the schema:

  • python-jsonschema (github)

The implementations do not behave consistently.

Preliminary Subjective Analysis

The following are the instructions that I would currently give. The goal here is of course to reach a consensus. I hope the imperative wording below does not make this impossible.

• Acknowledge that RFC 3986 (URI) and RFC 3987 (IRI) do not define 1 unique equivalence relation.

• Acknowledge that RFC 3986 (URI) and RFC 3987 (IRI) do not define 1 unique, canonical normal form.

• Acknowledge that RFC 3986 (URI) and RFC 3987 (IRI) define only a very limited set of operations. For example they explicitly define how to resolve relative references but they do not define how to add a fragment to a URI/IRI or how to add a JSON pointer segment to a URI/IRI fragment.

• Acknowledge that RFC 3986 (URI) and RFC 3987 (IRI) do not define a model / data structure that is free of percent-hex-hex sequences (URIs/IRIs and percent encoding/escaping is not analogous to JSON and backslash encoding/escaping in this respect). The percent-hex-hex sequences "bleed out".

• Acknowledge that RFC 3986 (URI) and RFC 3987 (IRI) potentially contain open ended dependencies / references. For example:

  perhaps augmented by reference to additional rules provided by URI scheme definitions

  If JSON Schema depended on all scheme-specific rules:

  • The burden on implementers and schema authors would be too high. Almost all implementers and almost all schema authors will not be able to acquire a thorough knowledge of all scheme-specific rules.
  • The promise of forward compatibility would not be a serious one: New schemes and scheme-specific rules will emerge in the future. The stability of scheme-specific rules can not be guaranteed.

• Acknowledge that distrust is a major motivation for validation. Some people will look for weird edge cases to exploit. Others will produce them by accident. No URI is too weird to be forbidden.

• Acknowledge that whatever the JSON Schema specification describes is a consumer and a producer of URIs/IRIs. Becoming more permissive and becoming more restrictive can both be breaking changes (analogy: "Container<Cat> and Container<Animal> are mutually unassignable"). For example widening the set of allowed characters might be a breaking change, just like switching from URIs to IRIs (even though "all URIs are IRIs").

• Acknowledge that the JSON Schema specification does not assign 1 unique URI/IRI to each schema. The specification might even associate a schema with multiple equivalence classes of URIs/IRIs (the exact details are not clear to me). The meaning of phrases like "[...] the URI of the schema [...]" might not be obvious to everyone.

• Acknowledge that RFC 6901 (JSON Pointer) does not directly deal with URI/IRI equivalence.

• Acknowledge that the JSON Schema specification is the ultimate authority triggering the application of a JSON pointer.

  Here I feel like: "Why not just tell implementations exactly when (and when not) to apply a JSON pointer?". Registering JSON pointers as fragment identifiers for application/schema+json is a good idea but this alone might not be enough. It would seem like dereferencing using JSON pointers can conflict with dereferencing relying on (some currently implicit) URI/IRI equivalence relation. Challenges: reconciling the W3C fragid best practices, "$id"s with empty fragments (when can we assume the media type application/schema+json?), "$id"-less root schemas, external "$id" "overriding" (seems very powerful/unrestricted!).

In my dreams, part I:

• Eccentric rich person: «Hello, I am an eccentric rich person. I give you a million dollars if you could do a little task for me.»
• Me: «Ok»
• Eccentric rich person: «I have here a bunch of JSON schemas. Could you write a function that generates exactly those strings: they must conform to the absolute IRI syntax and they must be dereferenced to one of my schemas when used as value of "$ref".»
• Me: «Maybe if the function could take the arguments -»
• Eccentric rich person: «No cheating! I have used an absolute URI as "$id" in all root schemas. This certainly should be really simple.»
• Me: «I don't know. I can ask in the forum but my hopes aren't high.»

[jdesrosiers]

There may be some cleanup we can do in this area, but I don't think it's a bad as you're making it out to be. The spec says that $ids should be normalized. That would mean that your first example has two different schemas identified by the same identifier, which the spec says not to do and that inconsistent results are to be expected. The second example I think is just a bug in python-jsonschema. The fragment needs to be URI-decoded before it can be processed as a JSON Pointer. The decoding result should be a valid JSON Pointer pointing to a valid location.

Beyond that, I accept your point that the concept of normalization is open-ended and we don't clearly define what is expected. It could be helpful to include guidance on what types of normalization are expected (case, %-encoding, path-segment) and what isn't (schema, protocol).

[Julian]

The fragment needs to be URI-decoded before it can be processed as a JSON Pointer. The decoding result should be a valid JSON Pointer pointing to a valid location.

We have no test for this behavior at the minute, so if it's indeed correct, pointing to where in the spec it says to do this and adding one would certainly be nice!

[watuwo]

but I don't think it's a bad as you're making it out to be

I do not consider this a fundamental, fatal flaw of the JSON Schema specification either (btw: I like JSON Schema, the test suite and the implementations). These could be technicalities that can be sorted out.

But my impression is: I am not sure whether the JSON Schema community has really accepted this to be a topic affecting the specification and not just the implementations (especially the limitations of RFC 3986/3987). This uncertainty about the awareness and acceptance of challenges lead me to formulate these "Acknowledge ..." suggestions.

Btw. I am not saying "JSON Schema must define a unique normal form of URIs/IRIs" but I believe that if JSON Schema doesn't define one, then there is none (at a JSON Schema level; even if the URI/IRI library of your choice offers an unparametrized normalize function; analogous for equality / ultimate base URI/IRI / external associations / URI/IRI output format / ...).

If you believe that

The spec says that $ids should be normalized. [...] [The] first example has two different schemas identified by the same identifier

then consider this schema

{
  "$schema":"https://json-schema.org/draft/2020-12/schema",
  "$id": "http://example.com/test-001b",
  "$ref": "http://example.com/foo%2Ejson",
  "$defs": {
    "abc": {
      "$id": "http://example.com/foo.json",
      "const": 2
    }
  }
}

hyperjump (online) and jschon (online) reject the schema (treating "http://example.com/foo%2Ejson" and "http://example.com/foo.json" as not $ref-equivalent even though they are supposed to be "the same"). json-everything (online) finds the instance 1 to be invalid (treating the URIs as $ref-equivalent).

pointing to where in the spec it says to do this

I have already expressed my confusion and unfortunately I can not give a definitive answer to that (I suppose you are not looking for an answer from me anyways). In the future it might also be interesting for the test suite how this kind of dereferencing interacts with externally assigned identifiers and non-schema-locations (possibly relevant for OpenAPI, just a hunch).

[jdesrosiers]

then consider this schema

I didn't express that the right way, but the answer is still the same. The $id used in that schema is not normalized. The spec says that your $ids SHOULD be normalized and if they aren't you could get inconsistent results. Maybe the spec could be more prescriptive about what it means for an $id to be "normalized", but it does call out that this is a case that could lead to inconsistent results.

FYI, this discussion has inspired me to introduce some normalization in my URI comparison in hyperjump.

pointing to where in the spec it says to do this

Without looking, I'm not sure the spec says that the fragment needs to be decoded, but I don't think it needs to. A URI is a specific serialization of a string (using %-encoding). When you extract parts of a URI to use individually (whether that's a path segment, query, or fragment), you need to remove the URI serialization to get the actual value. %-encoded characters are not an intrinsic part of the value, they are just part of the serialization.

[watuwo]

%-encoded characters are not an intrinsic part of the value, they are just part of the serialization.

That's the behavior we would want and expect (coming from JSON, where this would be true for backslash escaping). Unfortunately the URI/IRI standards have to deal with historic behavior and there it is different (and weirder). Consider this example: "http://example.com/abc?a=b&3Dc" and "http://example.com/abc?a%3Db=c" (the percent encoding is used on a higher level than URI).

"normalized"

This whole discussion would probably not exist if RFC 3986/3987 had used a term like "mangled" instead of "normalized".

hyperjump

It is a nice library and the online tool is also very useful e.g. for figuring out how things are intended to work (like $dynamicRef). I do consider the library safe for use with trusted schemas (the only kind of schema I have ever worked with). Totally unrelated to this discussion (please ignore, if you don't find it useful): there are two minor typos in the "Bundling"/"Usage" section of the README (missing comma in the first schema, "https://example.com/main" instead of "https://example.com/string" in the bundle (only in the documentation, not in the bundle generated)).

[jdesrosiers]

Consider this example: "http://example.com/abc?a=b&3Dc" and "http://example.com/abc?a%3Db=c" (the percent encoding is used on a higher level than URI).

I assume the & in the first URI was intended to be %. I think these URIs unambiguously represent two different URIs and this is an example of what %-encoding is for. The first represents { "a": "=c" } and the second is { "a=": "c" }. The only way to express that is with %-encoding. = is part of the syntax of the query string and %3D is not.

there are two minor typos

Thanks for pointing it out!