Skip to content

Latest commit

 

History

History
91 lines (62 loc) · 5 KB

2022-04-08-cref-for-ambiguity-and-fix-later-gh-spec-issue-1172.md

File metadata and controls

91 lines (62 loc) · 5 KB

Acknowledge ambiguity in additionalProperties behaviour and fix after patch release

  • Status: accepted
  • Deciders: @relequestual @gregsdennis, @jdesrosiers, @karenetheridge
  • Date: 2022-05-19

Related...

Issue: #1172

Discussion: json-schema-org/community#57

Pull Request: #1203

Context and Problem Statement

When we changed the specification to use annotations as the context in which some keywords behave, we included a clause that allowed implementations which didn't use annotations to optimize the processing of additionalProperties in another way which produces the same effect as the prior behaviour. This section created an ambiguity in terms of the resulting output format, but not validation.

We needed to decide on how to proceed for the patch release of the 2020-12 version of the specification.

The two above links are to a GitHub Discussion and a GitHub Issue detailing the problems. Details with an example of the problem can be seen in the Discussion's opening post specifically.

Decision Drivers

  • The "patch release" should not change anything functionally
  • Annotations as they are, are confusing to users, implementers, and specification editors alike
  • Patch release is behind schedule
  • There are currently no tests for the output format
  • It's hard to see any immediate consensus on changing the annotation based behaviour

Considered Options

Decision Outcome

Chosen option: "Acknowledge and accept that two approaches and results are allowable", because

  • Leaving it "as is" will continue to cause confusion
  • The change is non-functional which is required for the patch release
  • The patch release is behind schedule
  • Finding consensus of other solutions proved to be difficult
  • There's no test suite for the output format, so it's not easy to see unintended consequences of a functional change
  • We need to properly re-evaluate annotation collection and how annotations are used by other keywords

Positive Consequences

  • Patch release can move forward
  • Validation result is not impacted
  • Confusion is at least seen and acknowledged
  • Implementations which pick either approach are seen to be compliant

Negative Consequences

  • May have an impact for downstream tools which process full output data
  • A test suite (not yet developed) which covers this situation needs to allow for multiple valid answers

Pros and Cons of the Options

Leaving it "as is" and do nothing

Agree to do nothing and hope for the best. There isn't any downstream tooling yet anyway.

  • Good, because no functional change
  • Good, because no impact on downstream tooling
  • Bad, because leaves a known ambiguity in the specification

Pick one / Revert to draft-07 behaviour / Reinterpret annotation collection

  • Good, because ambiguity is removed
  • Good, because not many tools will be effected
  • Bad, because it can be seen as a functional change (not really allowed for the patch release)
  • Bad, because it can break existing implementations and downstream tools
  • Bad, because without a test suite it's hard to see unexpected consequences

Links