require $schema in schemas

[gregsdennis]

Resolves #1420

[jdesrosiers]

Glad to see these this change happening!

Something that's missing is dialect inheritance in embedded schemas. An embedded schema that doesn't declare $schema inherits the dialect of the schema it's embedded in (how ever the parent schema's dialect was determined, not necessarily $schema).

[jdesrosiers]

I feel like this could be organized a bit better. There are four rules for determining the dialect, but they're not all in the same place and not presented consistently. The first rule is in a different place than the other three, Those three are in the same place, but the third and fourth are presented differently (as a list) from the second.

I think this could be more clear if the rules for determining the dialect were presented consistently and in one place in a way implementers could follow like an algorithm. I think the third and fourth rules are presented in this way, but it would be nice if the first and second were included as well.

Also, it just occurred to me that this is all defined in the section about the $schema keyword. Since the $schema keyword is only one one part of dialect determination, it seems like it would be better to talk about dialect determination in it's own section that references to $schema keyword as one way the dialect could be determined.

[gregsdennis]

There are four rules for determining the dialect

This PR is a realization of the discussion we had in #1420. In that discussion, we identified three prioritized steps:

1. The $schema keyword
2. The schema media type parameter (if the schema was retrieved over HTTP) (optional)
3. The user provides a default through an implementation's API in some way. (optional)

What is this fourth rule?

[jdesrosiers]

The fourth rule is an embedded schema inheriting from its parent context. I think it belongs after the media-type parameter and before the user provided default.

I had forgotten about that one when I wrote that issue, but it's definitely part of the process. If you'd rather address that in a separate PR, I'm ok with that.

[Relequestual]

Can't wait to see the tests for this get merged! =D

[jdesrosiers]

This looks great! I left a couple notes, but either could be address separately if we want.

[jdesrosiers]

I think this concept also applies to schemas embedded in other types of documents like OpenAPI. I'm not sure how this might be reworded to include that case, or if it should be considered a different case, or if that case should be addressed elsewhere entirely.

[karenetheridge]

We can say something like:

If the schema is embedded in a larger document (such as OpenAPI), the semantics for determining the dialect may be specified by that document's specification. Unless explicitly dictated by that document's specification, the presence of a $schema keyword shall always override the dialect imposed by the containing document.

[gregsdennis]

I like that @karenetheridge. I'll try to work some of that in.

Unless explicitly dictated by that document's specification, the presence of a $schema keyword shall always override the dialect imposed by the containing document.

I think this may be redundant given this is a prioritized list and the $schema requirement is higher on the list.

Unless you're saying the containing document's spec can say that $schema should be ignored. That seems like we're saying it's okay for a consuming specification to override this rule. I'd prefer such specs simply disallow using $schema so that there's no confusion.

[Relequestual]

I agree. Currently, the OpenAPI spec allows you to define a default dialect.

@karenetheridge What's the use case you see for allowing a containing document specification to override $schema for it's contained schemas?

[karenetheridge]

No, the other way around - the openapi spec has language about following jsonSchemaDialect to set the dialect for all contained schemas, but if one of those schemas has a $schema keyword in it, that overrides the jsonSchemaDialect. (Unless OpenAPI wanted to add a rule saying that $schema is no good here.)

[gregsdennis]

Right, so that falls in line with the precedence order here. $schema first, then media type (if it exists), then parent document, then config.

I think Ben was wondering about the edge case where a document wanted to override $schema. I'm not sure we can define requirements for that.

[jdesrosiers]

Can't wait to see the tests for this get merged! =D

I'm not sure much, if any, of this testable with our current setup.

[karenetheridge]

I don't know if it's been discussed elsewhere but there is still a problem with allowing $schema keywords to appear in non-root locations in the document -- because we also require that the schema must validate against its metaschema, and this requirement can be violated if a contained sub-schema uses a different dialect than the document root that conflicts in some way.

Are we expecting that implementations need to have a special evaluation mode when validating schemas, and somehow switch to a different metaschema when $schema keywords are encountered? We don't spell that out in the spec in any way, and instead assume that when a schema is being evaluated against its metaschema, we treat it just like any other data instance.

[karenetheridge]

I think we can go stronger here and say that if the schema is fetched over HTTP, it MUST respect the media type parameter if it is present, and add a reference to the section that defines the name and syntax of this header. This may be implied by the existing wording, but we can spell it out more explicitly.

[gregsdennis]

Is this not what it's already saying? 895 contains the "MUST" requirement. I don't want to call out HTTP; I'd prefer to stay more general and say that if the media type parameter is available in general. It could come from anywhere, e.g. the OS or app.

[karenetheridge]

I guess I was confused what "Implementations which support media type parameter inputs" meant. Does that cover "if you used HTTP, you better check the Content-Type header and do what it says"?

[gregsdennis]

I think it covers any scenario, including http, where you might receive a media type. So, yeah.

[karenetheridge]

We can say something like:

If the schema is embedded in a larger document (such as OpenAPI), the semantics for determining the dialect may be specified by that document's specification. Unless explicitly dictated by that document's specification, the presence of a $schema keyword shall always override the dialect imposed by the containing document.

[Relequestual]

Are we expecting that implementations need to have a special evaluation mode when validating schemas, and somehow switch to a different metaschema when $schema keywords are encountered?

Yup.

We don't spell that out in the spec in any way, and instead assume that when a schema is being evaluated against its metaschema, we treat it just like any other data instance.

First, we have to look at the definition of a Compound Schema Document...

A Compound Schema Document is defined as a JSON document (sometimes called a "bundled" schema) which has multiple embedded JSON Schema Resources bundled into the same document to ease transportation. - Core 9.3

I would argue that this defines any OpenAPI definition as a compound schema document.
While the examples in the apendix section is a JSON Schema, it doesn't have to be.

Then, the validation section...

Given that a Compound Schema Document may have embedded resources which identify as using different dialects, these documents SHOULD NOT be validated by applying a meta-schema to the Compound Schema Document as an instance. It is RECOMMENDED that an alternate validation process be provided in order to validate Schema Documents. Each Schema Resource SHOULD be separately validated against its associated meta-schema. - Core 9.3.3

Given this, we might want to tighten up the language of meta-schema useage for validation to make the target a "schema resource" to make this clearer? I don't know. Open to thoughts.

[gregsdennis]

Are we expecting that implementations need to have a special evaluation mode when validating schemas, and somehow switch to a different metaschema when $schema keywords are encountered? - @karenetheridge

Yup. - @Relequestual

I'm with Karen. I think a meta-scheam evaluating a schema should be no different than a schema validating an instance. I don't think it's too hard to achieve this.

Still, let's work that out separately from this PR, please.

I don't know if it's been discussed elsewhere but there is still a problem with allowing $schema keywords to appear in non-root locations in the document -- because we also require that the schema must validate against its metaschema, and this requirement can be violated if a contained sub-schema uses a different dialect than the document root that conflicts in some way. - @karenetheridge

I would argue that this defines any OpenAPI definition as a compound schema document. - @Relequestual

I don't think the comment was about OpenAPI, but rather any time a $schema is used in a subschema resource, which is allowed currently.

If the parent schema declares 2020-12 (which disallows array items, and it contains a schema resource that declares draft 7 which also contains an array items (valid in draft 7), then a pure meta-schema evaluation of the root schema would fail.

I don't know that the Compound Document definition applies to the above scenario like it does for bundling. I think it could be argued both ways.

I agree that there's no real way to handle this right now. Let's take another PR for that and consider this PR as a mere iteration.

These two topics combined intersect somewhat with this discussion about $schema in instances.

[Relequestual]

I don't think the comment was about OpenAPI, but rather any time a $schema is used in a subschema resource, which is allowed currently.

If the schema is embedded in a larger document (such as OpenAPI)... - One of @karenetheridge comments.

However, I agree, it applies more broadly.

Still, let's work that out separately from this PR, please.

I agree. As a reference, we discussed this at quite some length already: #936

[karenetheridge]

I agree. As a reference, we discussed this at quite some length already: #936

That issue is talking about how to evaluate with a schema when there are embedded $schema keywords that change the dialect midway through. The problem I raised is how to evaluate that schema as a data instance against its metaschema -- because the metaschema you're evaluating with is changing midway through the evaluation, but the normal evaluation process doesn't know anything about switching schemas depending on what it finds in the data.

[gregsdennis]

@karenetheridge I get what you're saying. I'll create an issue for it for us to discuss.