search

json-schema-org / json-schema-spec

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

Consolidate and clarify language around duplicate IRIs #1272

Closed handrews closed 2 years ago

handrews commented 2 years ago

Fixes issue #1271 and addresses one point mentioned in https://github.com/json-schema-org/json-schema-spec/issues/1059#issuecomment-1212726799 (but please do not drag the rest of that issue into this PR, thanks!)

The only actual changed requirement is the forbidding of "$id": "#", and "$id": "" which are confusing and are either pointless (in a document root where they resolve to the retrieval IRI, exactly as if $id was not present) or problematic (in an embedded resource root, where they produce duplicate IRIs for the embedded and containing resource).

This also consolidates the two different places where duplicate IRIs were addressed. Since the more general of the two paragraphs stated that this SHOULD be an error, I kept the SHOULD rather than the MAY that addressed only a subset of the cases. The SHOULD technically covered the subset as well anyway.

I have emphasized that "undefined" here means that the result, whatever it is, will not be interoperable (most likely, implementations will just return the last-seen schema under that IRI, but who knows).

Note that we could continue to allow "$id": "#" and "$id": "" and just assume that the SHOULD regarding duplicate IRIs is enough to discourage that. If that is the consensus then I can remove the commit that handles that part of the change.

handrews commented 2 years ago

Based on feedback so far I have removed the forbidding of certain $id values (and changed the title of this PR to match that). I did add extra wording in the section on subschemas with $id about how empty IRIs are problematic, as it seems useful to do that there. It links to the new section on duplicates.