Keywords alongside of `$ref`

[handrews]

An effect of moving to a delegation model for $ref (see #514) is that there is no longer any need to forbid adjacent keywords. This was mentioned in passing in the first comment but I wanted to call it out to get clear agreement (without getting bogged down in the very long and nicely resolved #514).

The resolution to #514 allows implementations to do inclusions under certain circumstances. This can be made to work with adjacent keywords by simply stuffing the included target under an allOf:

{
    "$defs": {
        "foo": {"required": ["f"]}
    },
    "required": ["a", "b"],
    "$ref": {"#/$defs/foo"}
}

is equivalent to

{
    "required": ["a", "b"],
    "allOf": [{"required": ["f"]}]
}

If there is already an adjacent allOf, the included $ref is simply appended to the existing list.

Any objections? It's extremely common to see people put keywords beside $ref even with all documentation saying that it is not allowed, so we really should make it more intuitive.

[gregsdennis]

I wonder how this would interact with #515. I think I mentioned it as a solution somewhere in there. I'll try to find the specific comment and link to it later, but I'm on my phone for the moment.

[handrews]

@gregsdennis it should be orthogonal. additionalProperties and additionalItems wouldn't be able to "see" through a $ref: they work within the same schema object, and $ref should not be special in that regard.

With $ref as delegation, it fits into the keyword taxonomy as an applicator keyword- specifically, it applies the schema at the target URI to the current instance location. This is why, when you want to inline the target schema, but there are adjacent keywords, you MUST wrap the inlined schema in an allOf.

Otherwise we're into schema merging territory which we will not be discussing here as that's what #515 is for. I'm serious about this, any discussion of topics belonging to 515 on this issue will lead to immediate deletion of the entire comment. I will probably cackle maniacally while doing so, in order to fit the mad dictator stereotype more fully. We don't need another 200+ comment issue, I filed this specifically to keep it separate.

[handrews]

(it's OK to talk about whether something would put us in merge territory, it's just not OK to drag actual proposals related to merging or similar stuff over here)

[gregsdennis]

I don't know if it's particularly an issue with this as a feature, but it would be fairly easy to create a contradictory schema.

For instance, if a $ref'd schema defines a maximum of 12, and the $ref has an adjacent minimum of 20, it creates a contradiction that will never validate any value.

Maybe this is something that we leave to the author to manage, but I figured it should still be mentioned.

---

Another thing that should be mentioned is that these refs could be internal or external. Internal refs are trivial, but I think we should account for the possibility of a $ref'd schema being of a different schema version, in which case simply housing it in an allOf would only work logically, not practically.

[handrews]

@gregsdennis in general it is very easy to create nonsensical / contradictory schemas with JSON Schema. The scenario you mention exists today- just wrap the $ref in an allOf and it's exactly functionally identical to the proposed adjacent-keyword behavior.

The adjacent keyword behavior is not actually new at all, it just removes an unnecessary allOf.

Also, the whole point of $ref as delegation was in order to let it work as kind of a logical inline but not really a physical inline because of things like differing meta-schemas. So I'm not sure I'm getting your point in the second part- I thought we had an exhaustive discussion of that already.

[gregsdennis]

So I'm not sure I'm getting your point in the second part- I thought we had an exhaustive discussion of that already.

I wasn't trying to bring in new discussion so much as clarify the equivalence in your opening comment.

[handrews]

@gregsdennis gotcha. Yeah, that was perhaps not as clear as it should be.

[Relequestual]

OOOOH. I hadn't realised the implication of making it clear that $ref was delegation...
This is brilliant and will solve a lot of questions (I hope).
I totaly think this is the right way to go!

[gregsdennis]

I was thinking on this some more and I realized a neat side effect of using the sibling $ref syntax: it enables an author to create "abstract" schemas, that is, schemas that depend on certain definitions but don't define those definitions themselves, instead relying on extending schemas to define them.

The example that came to mind was generic classes. If we consider .Net's List<T>, it's essentially an array where all of the items are the same type, but we don't know what type that is. So a schema might look like this:

{
  "id" : "http://dotnetschemas.com/list-of-T",
  "type" : "array",
  "items" : { "$ref" : "#/definitions/T" }
}

By itself, this schema would cause an error as T is not defined. But if we then extend (inherit) it, we can define T to be whatever we want.

{
  "$ref" : "http://dotnetschemas.com/generic-list",
  "definitions" : {
    "T" : { "type" : "string" }
  }
}

Of course, this particular example would only apply to languages which support generics, but there are likely other "abstract"-type use cases.

Maybe... it depends on how the $ref is dereferenced.

[epoberezkin]

The problem is that "$ref" : "#/definitions/T" will be resolved in the context of the first schema (i.e. won't be resolved at all).