search

json-schema-org / json-schema-spec

The JSON Schema specification
http://json-schema.org/
Other
3.43k stars 251 forks source link

Output unit schema inconsistent with spec #1504

Open tombentley opened 2 months ago

tombentley commented 2 months ago

The 2020-12 spec says this about successful validations:

The JSON key for failed validations is "error"; for successful validations it is "annotation".

A later sentence draws an explicit contrast for the case of nested results :

Note the plural forms, as a keyword with nested results can also have a local error or annotation.

But the output schema only defines a property for the plural annotations and not the singular annotation.

gregsdennis commented 2 weeks ago

The output schema defines error because errors are only strings. It doesn't define a subschema for annotation because annotations can be of any value.

tombentley commented 2 weeks ago

Wouldn't it be clearer to use annotation: true to define the property in that case? At least that way annotation is present in the schema. When I read the text I found it confusing that something was mentioned in the text (not in an especially clear way, imho) but not even present in the schema.

gregsdennis commented 2 weeks ago

I see your point. Intentionality is worth something.

I'll go ahead and reopen this, but it'll be for an errata correction. I'm not sure how to make that change since the file has already moved on to the next version of the output. This might need to be done in the website repo.

jdesrosiers commented 2 weeks ago

I'm not sure how to make that change since the file has already moved on to the next version of the output.

There's branch for each release. You can make the change on top of that branch.