Clarify whether plain name fragment URIs are canonical, and what it means if they are (or aren't)

[handrews]

There's a little confusion and ambiguity on this topic.

• Absolute URIs (with no fragment, not even an empty one) are definitely canonical, and identify the complete schema resource.
  • This implies that the same URI with an empty JSON Pointer fragment is non-canonical, but it should work, and it would be bad if an implementation did not support it.
• URIs with non-empty JSON Pointer fragment URIs, relative to the nearest base URI, are considered canonical.
• URIs with non-empty JSON Pointer fragment URIs, relative to a more distant base URI, are considered non-canonical and are not guaranteed to work.
  • This was the main point of the canonical URI stuff in 2019-09.
• URIs with plain name fragments aren't discussed as canonical or non-canonical
  • However, they only work with the nearest base URI so there's never any ambiguity
  • Therefore, plain name fragment URIs should always work.

Things to figure out:

• Is "canonical" the right term here? IIRC @awwright thought it was not, but I had a vaguely coherent reason as to why it was (which I should look up) and I was burnt out and needed to publish it so we did that. Probably not the best process.
• Should we be framing the requirement around what URIs MUST be supported and what MAY be supported differently, in order to capture the possibilities better?
• Are there other use cases I'm missing here?

[karenetheridge]

Is "canonical" the right term here?

Depends on how the term is going to be used :) I can give one example where a canonical URI that contains a plain-name fragment is not the most useful uri to be slinging around: when generating errors or annotations. I just ran into this today while implementing $anchor. Let me show an example that I'm using in my tests:

data: 1
schema:
{
  "$defs": {
    foo: {
      "$anchor": "my_foo",
      "const": "foo value"
    },
    "bar": {
      "$anchor": "my_bar",
      not: true
    },
  },
  "$id": "http://localhost:4242",
  "allOf": [
    { "$ref": "#my_foo" },
    { "$ref": "#my_bar" }
  ]
}

result:
{
  "valid": false,
  "errors": [
    {
      "instanceLocation": "#",
      "keywordLocation": "#/allOf/0/$ref/const",
      "absoluteKeywordLocation": "http://localhost:4242#/$defs/foo/const",
      "error": "value does not match"
    },
    {
      "instanceLocation": "#",
      "keywordLocation": "#/allOf/1/$ref/not",
      "absoluteKeywordLocation": "http://localhost:4242#/$defs/bar/not",
      "error": "subschema is valid"
    },
    {
      "instanceLocation": "#",
      "keywordLocation": "#/allOf",
      "absoluteKeywordLocation": "http://localhost:4242#/allOf",
      "error": "subschemas 0, 1 are not valid"
    }
  ]
}

So, the interesting thing here is that there are multiple errors generated on the far side of $refs where the URI being referenced has a plain-name fragment, and at least one level below the position where the identifier changes. We need to generate an error at this location, but we can't specify anything relative to the plain-name fragment, so we have to revert to the previous canonical uri to use as the base. So which uri is canonial for these locations? Is it possible to have more than one? Which one(s) should we hang on to as we traverse the schema, for the purpose of generating annotations and errors against that location? If an error is generated right at the location with the $anchor, should we use its uri as the location of the error, even though an error one level below it doesn't use that uri? Would that be confusing?

[handrews]

@karenetheridge

The "canonical" link relation type is defined in RFC 6596, and our usage should be roughly compatible with that. It is linked under § 8.2.2 The "id" keyword in the spec.

Your example definitely shows that absoluteKeywordLocation can't use a plain name fragment, at least not unless we then add a separate relative JSON pointer, and I do not want to go there.

So the answer to the question "what form should be used for consistent reporting of locations, including keyword locations that are not themselves schema objects" is clearly "Use the JSON Pointer from the nearest $id (or appropriate fallback base URI).

The other question around how we talk about canonical URIs is in that they MUST be supported, while non-canonical URIs, at least those involving JSON Pointers from other base URIs, MAY be supported, but don't have to be.

However, plain name fragments MUST be supported, so maybe it's just a case of cleaning up the language there. And also around the empty fragment JSON Pointer fragment, which also MUST be supported even if the, um... most canonical? URI for schema resource roots is one without a fragment at all.

[ssilverman]

@handrews Apologies for the nitpick: did you mean to use "are" and not "or" in the issue title? I'm trying to understand it precisely.

[ssilverman]

So the answer to the question "what form should be used for consistent reporting of locations, including keyword locations that are not themselves schema objects" is clearly "Use the JSON Pointer from the nearest $id (or appropriate fallback base URI).

I'm just ruminating on the example given above. Given these four absolute locations:

1. http://localhost:4242#/$defs/foo/const
2. http://localhost:4242#/$defs/bar/not
3. http://localhost:4242#/$defs/foo
4. http://localhost:4242#/$defs/bar

Without saying anything about being canonical, I suppose they could also be expressed as:

1. http://localhost:4242#my_foo/const
2. http://localhost:4242#my_bar/not
3. http://localhost:4242#my_foo
4. http://localhost:4242#my_bar

I'm just trying to wrap my head around @handrews's comments above and comparing these lists is helpful to me. It also makes sense why "use the nearest $id" might be good language.

[handrews]

@ssilverman no, your second block of URIs is invalid. You cannot mix plain-name and JSON Pointer syntax.

[ssilverman]

Ok, thanks for clarifying that.

[ssilverman]

So what about “or” vs. “are” in the title?

[awwright]

"canonical" as opposed to what? If we're talking about a link relation to apply to an $id keyword, I think I brought up an issue where rel=self makes more sense than rel=canonical.

[karenetheridge]

Canonical in this case means the fully-resolved uri associated with the current subschema location, derived from the nearest $id (as there could be multiple $ids up the heirarchy that would allow the current location to be referenced from a number of different uris).

This SHOULD be an absolute uri, so long as there is an absolute uri provided as the base uri for the entire document, or there is an absolute uri as an $id somewhere up along the way. It will never contain a plain-name fragment (as per discussions above in this thread), but it could contain a json pointer fragment if this exact location doesn't have an $id.

Hopefully I didn't get that too wrong. I'm at present in the middle of implementing $id and $anchor logic in my implementation so I'm up to my eyeballs in URI terminology :)