Improve handling of oneOf error reporting

[awwright]

In cases where oneOf is used for multiple mutually exclusive options, it is frequently the case that the option to pick is a single key within the instance. E.g. the "type" property will be from the enum "Animal, Vegetable, Mineral" and the appropriate schema to apply is picked based on the value of this property.

Right now, all schemas must be tested (similar to an O(n) operation). Only one schema corresponding with an e.g. "type" property need be tested (similar to an O(log n) or O(1) operation), and only errors against that schema need be reported. Otherwise we get bizarre, non-helpful errors like so:

(1 of 1) instance.o3 is not exactly one from <http://example.org/Animal>,<http://example.org/Vegetable>,<http://example.org/Mineral>

[awwright]

Upon further investigation, this is probably a mis-use of JSON Schema.

If there's multiple different, but similar, schemas, they should each get a different schema URI.

[handrews]

This is addressed in much more detail in #64 because I did not realize that you had re-filed the bounding proposal from the old wiki here in this issue under a different name.

This is why I am so bothered by all of the open issues and pages in the old repo. Leaving them open without any link to this repo makes it look like they're not tracked here, which means duplicate filings.

Would you be willing to close this one? Or I could close the other and import all of the info from it, but the title of this issue is much more narrow.

[handrews]

Now that we have const it is easy to check that keyword first and short-circuit any evaluation. I don't think there's anything else needed to specifically address this issue, and #64 covers other related concerns. Can we close this one?

[awwright]

I think we can still offer some guidance on how validators can expose these cases to developers.

They can produce output like:

(1 of 2) instance.o3 is not exactly one from http://example.org/Animal,http://example.org/Vegetable,http://example.org/Mineral
(2 of 2) (if instance.o3.type=="animal") Missing expected property "species"

[handrews]

@awwright true, but does that go in the spec or on the web site? An implementation notes section perhaps? I'm asking because I don't know- I do not have an opinion on where it should go, I'm just trying to learn what the appropriate scope for this sort of thing is in a spec.

[awwright]

The spec is probably an appropriate place for a limited amount of advice on how to write the implementation.

JSON (RFC7159) might be a good example, while all it is is a media type; the RFC also has a brief section on parsers.

[handrews]

Right now, all schemas must be tested (similar to an O(n) operation). Only one schema corresponding with an e.g. "type" property need be tested (similar to an O(log n) or O(1) operation), and only errors against that schema need be reported.

@awwright The selectWith proposal in #64 fixes exactly this, without changing validation at all. It just enables an optimization and better error reporting.

[epoberezkin]

I summary of our conversation with @handrews: I do not understand how the value that selectWith points to maps into any subschema inside oneOf/anyOf without using any complex algorythms.

The alternative idea is to have another validation keyword, e.g. selectCases that would have a map of subschemas.

[handrews]

@epoberezkin I'm not at all attached to the instance pointer version of selectWith. It could work with schema pointers you need to be able to extract the schema from each branch and apply it. Honestly, I'm becoming less supportive of this option. It fits the declarative approach but doesn't make it that much easier to understand.

In my experience, engineers needed to ramp up a bit on how to use "oneOf" but settled into it pretty well once they tried it out a bit. That's my main reason for continuing to object to imperative approaches. It's a dramatic departure to solve a "problem" that in my experience just needs a bit of explanation and best practices documentation.

The web site needs a schema patterns cookbook section, really.

[handrews]

So there seems to be a consensus developing around @epoberezkin if/then/else proposal in #180 (which avoids the complexity of switch that was my strongest objection to that option).