Bundling of Draft-07 schemas with relative URI references does not work

[michalstutzmann]

Here's a example with Draft-07 of the JSON Schema spec:

$ jsonschema --version
14.9.0

$ cat schema.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "test.schema.json",
  "allOf": [
    {
      "$ref": "../dependency.schema.json"
    }
  ]
}

$ cat ../dependency.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "dependency.schema.json"
}

$ jsonschema bundle schema.schema.json --resolve ../dependency.schema.json
error: Could not resolve the reference to an external schema
  at identifier ../dependency.schema.json
  at file (...)schema.schema.json

This is likely because you forgot to import such schema using `--resolve/-r`

I'm not entirely sure if such references are allowed by the spec. However, the Draft-07 specifies that a $ref can contain URI reference. URI reference can be a relative reference: https://datatracker.ietf.org/doc/html/rfc3986#section-4.1, https://datatracker.ietf.org/doc/html/rfc3986#section-4.2.

[jviotti]

Hey @michalstutzmann ,

This is a gray area, but an interesting one. I think we can indeed support it, but just to explain the context:

• With the first schema, when you set $id to test.schema.json you are saying that the identifier of that file is JUST test.schema.json. That means you explicitly opt out from the default URI being the file URI to such file, like file:///foo/bar/test.schema.json
• Then in that file you reference ../dependency.schema.json. Given your explicit $id is test.schema.json, that is relative resolution between 2 relative URIs, which is undefined as per the URI RFC
• So when you try to bundle, even though you manually include dependency.schema.json, the schema will try to literally find a schema with an $id of ../dependency.schema.json and not dependency.schema.json

In general, we strongly discourage $id's that are not absolute URIs. And in your case, explicitly setting them to the file name actually makes what you would expect to happen more complicated. For example, if you would drop $id from both cases and just let the file:// default takes place, everything works beautifully (setting absolute $ids in both cases will also make it work fine):

$ cat test.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "allOf": [
    {
      "$ref": "../dependency.schema.json"
    }
  ]
}

$ cat ../dependency.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#"
}

$ jsonschema bundle test.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "file:///Users/jviotti/Projects/playground/test/schemas/test.schema.json",
  "allOf": [
    {
      "$ref": "../dependency.schema.json"
    }
  ],
  "definitions": {
    "file:///Users/jviotti/Projects/playground/test/dependency.schema.json": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "file:///Users/jviotti/Projects/playground/test/dependency.schema.json"
    }
  }
}

But what makes me think is whether we can or should default a relative URI as an identifier as relative to the file:// URI base, which would make this work. But not sure if it has unintended consequences.

Alternatively, maybe worth linting cases where the $id equals the file name as "that's probably not what you want"

[Adityakumar37]

Hi @michalstutzmann
Are you currently working on this issue?
If not, I’d be happy to take a look and explore a potential solution based on the discussion above.

[jviotti]

@Adityakumar37 I think there is a step before fixing it: figuring out how to do it. If you want to help, I'd encourage you to open some threads about this in the JSON Schema Slack. See what the rest of the TSC thinks in conjunction with maybe a careful re-evaluation about what the specs say about this.

I think it's clearly a gray area. Maybe the conclusion is to make it work somehow, or to just reject it with an error. Not sure to be honest! But feel free to kickstart the conversation and CC me, and then we'll both learn :)

[michalstutzmann]

Thanks for the analysis @jviotti.

You had a good point that with the explicit $id we may opt out from using the retrieval URI as the base URI for the document. The spec discusses this matter here: https://json-schema.org/draft-07/draft-handrews-json-schema-01#id-keyword

Agree that this has to be further discussed before any implementation.

[michalstutzmann]

@Adityakumar37 I'm not working on the implementation, please fell free to own this issue, thank you!