JSON Schema: Using $ref to an internal $id is flagged as an error

[GrahamLea]

Describe the bug
When linting a self-contained JSON schema, using a $ref to refer to an internal sub-schema by $id is reported as an error.

To Reproduce

1. Grab the "Using $id with $ref" example from Understanding JSON Schema
2. Run spectral lint -F hint -v schema.json

Expected behavior
Should be a valid schema

Actual behavior

Found 52 rules (36 enabled)
Linting <file>
JSON Schema detected
JSON Schema (loose) detected
JSON Schema Draft 7 detected

<file>
 28:15  error  invalid-ref  ENOENT: no such file or directory, open ''

✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)

Environment:

• Library version: 4.2.0 (I can't test with latest due to “Cannot read property 'lastIndexOf' of undefined” when passing filename to spectral lint #1097)
• OS: Mac OS Mokave
• Node: v13.13.0

[nulltoken]

@GrahamLea Interestlingly the latest develop tip yields a different error

$ yarn cli lint -v ./repro/schema.json
yarn run v1.19.2
$ node -r ts-node/register -r tsconfig-paths/register src/cli/index.ts lint -v .
/repro/schema.json
Missing baseUrl in compilerOptions. tsconfig-paths will be skipped
Found 81 rules (65 enabled)
Linting c:/_work/spectral/repro/schema.json
JSON Schema detected
JSON Schema (loose) detected
JSON Schema Draft 7 detected

c:/spectral/repro/schema.json
 1:1  error  invalid-ref  '#address' JSON pointer is invalid

✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)

So, that's progress (the error looks a little more to the point), but indeed, it seems we're not there yet...

[nulltoken]

@P0lip The invalid-ref error seems to point at json-ref-resolver.

Is it possible that it tries to reference the internal Json Schema reference as a Json Pointer?

[P0lip]

Is it possible that it tries to reference the internal Json Schema reference as a Json Pointer?

I believe what it yells at is

"$ref": "#address" 

This is not a valid JSON Pointer.
In general, we don't support referencing $ids, so the example won't work.

[GrahamLea]

Okay. I'm pretty new to JSON schema. Would you mind explaining briefly why it's not a valid pointer? Any ideas why it's documented in this popular online guide and it works in 2 schema parsers I'm using when it's not valid? Just trying to understand the landscape.

[P0lip]

Would you mind explaining briefly why it's not a valid pointer?

Spectral does not support resolving based on $id - it's the property that's simply unrecognized by us.
If you want to reference a place in the document, you need to use a valid JSON Pointer, such as #/definitions/address, as explained in the extending section of the article you linked.

Any ideas why it's documented in this popular online guide and it works in 2 schema parsers I'm using when it's not valid? Just trying to understand the landscape.

Spectral is technically not a JSON Schema validator, therefore we don't support all of the resolving features that JSON Schema provides.
I'm not sure whether I was helpful or not, but please do feel free to ask further questions if something is uncertain.

[philsturgeon]

Context: Seeing as Spectral is a tool which aims to work with OpenAPI and JSON Schema, but those two formats are only mostly compatible, there are a few quirks like this which pop up.

OpenAPI does not allow $id, so resolving via $id is commonly not supported in tooling which works with OpenAPI, even though a lot of that tooling says it supports JSON Schema too. I know. This is a mess.

Seeing as OpenAPI v3.1 will be proper JSON Schema, $id will be allowed, and all JSON Ref tooling is now scrambling to add proper support. We're ditching our own json-ref-resolver to help json-schema-ref-parser get better, and they're adding $id support, so soon this problem will have gone away.

tldr: for now please try and avoid $ref'ing to $id and point to its location in the file using a more standard JSON Pointer instead.