hyper-schema: LDOs and anyOf/allOf/oneOf/not/dependencies

[handrews]

I think it would be a good idea to clarify the use of LDOs with the combinatoric keywords. I think this is what should happen, but I'm not sure:

• An LDO may only be used with an instance if the instance is valid against the schema in which the LDO appears.

  • LDOs from the valid branch of a "oneOf" can be used, but not any of the others
  • LDOs from each of the valid branches of an "anyOf" can be used
  • LDOs from a schema value in "dependencies" can only be used if the property key controlling that schema is present in an object instance

• LDOs within a "not" cannot ever be used (I just can't figure out how using them would make any sense)

• What happens if LDOs in "allOf" branches or in valid "anyOf" branches define links with the same "rel" values?

  • Could just mean multiple links are available
  • What if the resulting URIs are different? There is no way to tell which is intended, is there?

[awwright]

This is my understanding as well.

Links never replace each other, there can be multiple links with the same relationship. The best example is the "stylesheet" relationship. Links can also have multiple "self" "author" "alternate" "tag" and "type" relations, among others.

[handrews]

Sounds good. I'm trying to figure out a situation in which an API client might want to follow a link with a particular relationship and not be able to decide among multiple links with that relationship, but I think I'm fabricating that problem out of nothing.

Certainly for "stylesheet" and most of the others, if you have multiple, that just means you need to loop over them and look at each of them.

Multiple "self" links are a bit more confusing for me, although I may just be misunderstanding some aspects of "self". I have only used "self" in a root schema. Is the "context" which is identified by self the immediate containing schema or is it the schema document? In other words, does it make sense to have a "self" link in a subschema?

[awwright]

One case is if you're creating a front page of blog posts (e.g. list the 20 most recent blog posts in reverse chronological order), you have an array of JSON instances that each have their own URIs.

[handrews]

Why would you use "self" instead of "item" in that case?

[handrews]

I am assuming that by "array of JSON instances" you mean a single JSON document that validates against a particular schema, and the LDO with the "self" link is in the "items" (or "additionalItems") schema.

[awwright]

An "items" link would be from some sort of collection of posts, with a link pointing to each blog post.

The blog post itself would also have a "self" link (to itself) that gives itself a URI.

[handrews]

I guess I'm having trouble understanding the distinction between a list of blog posts in a JSON document and a collection of posts, but I am fine with the use case and can read up more on my own.

What about readOnly? Do we define that a particular bit of an instance is read only if any schema against which it validates sets readOnly to true? Or do we require some mechanism to resolve ambiguity (e.g. $use in #98) if different applicable schemas have different readOnly values?

Saying that one true readOnly takes precedence over any number of false ones is probably easiest.

[awwright]

Honestly, idk.

Technically, "properties" and "items" are just keywords for validation. All they do is return true or false.

People have been reading in that we can recursively apply the semantics, and that's fine too. Maybe we should make that more explicit.

The best advice I've got for handling metadata keywords like readOnly or description is... use common sense.

I tend to think all keywords can be defined multiple times, and they all apply in that case.

It'll be something we deal with once we understand better what the implementations look like.

[handrews]

It'll be something we deal with once we understand better what the implementations look like.

LOL this whole issue is because I have a code file open trying to implement this right now :-)

Algorithm looks something like this (for the whole thing, keep track of hyper-schema base and apply it appropriately):

For each JSON Pointer that resolves to a value in the instance:
1. Collect the schemas against which it validates (so prune out any "not" schemas, the non-validating branches of "oneOf" and "anyOf", and any "dependencies" schemas that don't apply).
2. Extract all LDO lists and concatenate them. This is the set of links originating from this point in the instance.
3. If any of the schemas set readOnly to true, consider this point in the instance to be controlled by the server.
4. Do... something? with the media objects? I haven't need to use these keywords yet, so I haven't thought about it.

If the representation in-memory is changed in such a way that validation changes, such as changing which branch of a oneOf is valid, then this all needs to be re-built before using any links.

[handrews]

The most urgent part of this was addressed by PR #251 (I just forgot to reference this issue).

While there are other topics here (such as exactly how to merge LDOs), I think that as we come to understand those better through implementation, we should create individual issues for them.

For now, we clarified that only schemas that validate apply hyper-schema keywords to instances, and nothing under "not", at any level of depth, even if there's another "not" reversing the first, ever applies hyper-schemas. This makes the implementation needs clear and avoids the most problematic cases. So I'm considering this fixed.