🧹 Clarification: Output schema is confusing

[lud-wj]

Specification section

This is about the "Basic" output description: "https://json-schema.org/draft/2020-12/json-schema-core#section-12.4.2"

What is unclear?

Given this example for the "Basic" format:

{
  "valid": false,
  "errors": [
    {
      "keywordLocation": "",
      "instanceLocation": "",
      "error": "A subschema had errors."
    },
    {
      "keywordLocation": "/items/$ref",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point",
      "instanceLocation": "/1",
      "error": "A subschema had errors."
    },
    {
      "keywordLocation": "/items/$ref/required",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point/required",
      "instanceLocation": "/1",
      "error": "Required property 'y' not found."
    },
    {
      "keywordLocation": "/items/$ref/additionalProperties",
      "absoluteKeywordLocation":
        "https://example.com/polygon#/$defs/point/additionalProperties",
      "instanceLocation": "/1/z",
      "error": "Additional property 'z' found but was invalid."
    },
    {
      "keywordLocation": "/minItems",
      "instanceLocation": "",
      "error": "Expected at least 3 items but found 2"
    }
  ]
}

I feel like it should be valid against {"$ref": "https://json-schema.org/draft/2020-12/output/schema#/$defs/basic"}, but it is not. It is only valid agains {"$ref": "https://json-schema.org/draft/2020-12/output/schema"} which is expected.

But if you remove {"$ref": "#/$defs/flag"} in https://json-schema.org/draft/2020-12/output/schema#/anyOf then it is no more valid against {"$ref": "https://json-schema.org/draft/2020-12/output/schema"}

Validation passes if we add the "keywordLocation": "", "instanceLocation": "" at the top level.

And now the following is valid against ...#/$defs/basic:

{
  "valid": false,
  "keywordLocation": "",
  "instanceLocation": "",
  "errors": [
    {
      "valid": 123,
      "some": "thing"
    }
  ]
}

Because, if I understand correctly, it still validates flag only.

Proposal

Do you have an idea to make the text more clear?

It's probably the wrong place for this issue because I'd prefer to change the spec itself:

• Define "Flag" format for the top level of the ouput only
• Do not require instanceLocation and keywordLocation for the top level

Thank you

Do you think this work might require an [Architectural Decision Record (ADR)]? (significant or noteworthy)

Not sure

[gregsdennis]

For the next version, the output had been extracted to its own spec. It has also been overhauled.

Have a read of my blog post on the upcoming changes.

https://json-schema.org/blog/posts/fixing-json-schema-output

Also know that this isn't final; it still needs some work before release.

[gregsdennis]

I've added this to the output project. Check that out to see other proposals in progress.

[lud-wj]

Gosh I was reading the blog but as it was from 2022 I assumed that the current spec I found was the result of your experiments.

Thank you, I'll go back to the example from the blog.

[lud-wj]

I guess we can close this, no?

[gregsdennis]

Yeah, we've had "delays".