Media type registration

[jdesrosiers]

The JSON Schema specification defines the application/schema+json and application/schema-instance+json, but these media types have never been officially registered with the IANA. We're in the process of getting those media types registered. We met yesterday to discuss our approach and some potential problems.

What we define should work for all past a future releases of JSON Schema and their existing implementations as well as custom versions such as OpenAPI and MongoDB. In other words, we're not designing something ideal from scratch. We're defining something that is compatible with how past and current implementation use these media types.

The approach we are taking is to standardize only dialect identification in the media type registration and deferring the rest of how to interpret the document to the specific JSON Schema specification that was identified. For example, if http://json-schema.org/draft-07/schema# is identified, then the document should be interpreted based on the draft-07 specification.

These are all ways the dialect can be identified with items at the top of the list taking precedence over items lower in the list.

• The $schema keyword
• The "schema" media type parameter
• The context of the enclosing document. This applies only when a schema is embedded within a document. The enclosing document could be another schema in the case of a bundled schema or it could be another type of document that includes schemas such as an OpenAPI document.
• If none of the above result in identifying the dialect, client behavior is undefined.

However, this doesn't technically work for 2019-09 and 2020-12 because it's not $schema that determines how a schema is processed, it's $vocabulary. That leaves us with only bad options. Here are some of the things we discussed.

1. Standardize $vocabulary as well as $schema.
   This isn't a good option because $vocabulary is still evolving and is likely to change.
2. Introduce a new keyword that declares the core vocabulary and standardize that only instead of all of $vocabulary.
   That's more likely to be stable than $vocabulary, but since it's a new keyword and part of the vocabulary system that is likely to change, it's very possible we don't get this right the first time.
3. Use the $schema of the meta-schema instead of the core vocabulary declared in $vocabulary to determine how to process the schema.
   Although technically not correct, this seems to be the approach that most implementations have taken because using $vocabulary for core vocabulary identification is somewhat problematic. There were some comments that this approach would allow you do some strange things. I didn't follow that in the discussion. This would be a good place to give an example of what that meant.

[jdesrosiers]

Here's another option. It's not perfect either, but while writing this up I remembered that this was how I reconciled this problem in the first place. If this is how we want to approach it, the registration should be updated to make this clear.

It should say that if the identified dialect is not directly understood by the client, information about how to process the schema may be encoded in the meta-schema identified by the dialect id. Then implementations that support 2019-09 and 2020-12 know to look for a known core vocabulary declaration in the $vocabulary keyword.

That's pretty open ended, but it's compatible with all existing versions and doesn't constrain us in the future. We're free to change $vocabulary however we want to in the future or use some other mechanism entirely.

It's not perfect because it doesn't fully define how to determine which specification to use to process the schema, it delegates some of that the identification process to individual dialects. But, it works and it's compatible with past and future. I think this is the best option we have.

[handrews]

@jdesrosiers

The process I defined is not dependent on the standard meta-schemas. It requires a meta-schema that is self describing ($id == $schema) at some point in the chain, but that doesn't need to be the official meta-schemas.

Ah, right- you are correct. However, a self-describing meta-schema that is also non-standard (and does not use $vocabulary) is an ambiguous case.

I don't agree with the rest of your response, but I don't have the spoons to unravel it right now. I know you're in a rush to do this, but I just cannot keep up with the pace of this conversation right now.

[jdesrosiers]

@awwright

I call it a "heuristic" because we don't have a written standard. There is no guidance on how one validator may incorporate historical specifications into a validator.

Ok. I see how you got there. However, I don't agree with your conclusion. Even though no individual spec tells you what to do, you can apply the rules from each spec version and get an unambiguous result. There are cases where no spec versions will claim the schema. In those cases you can use a heuristic or refuse the schema, but those aren't the cases I'm talking about in this thread. I'm convinced that it's not possible to have two different spec versions lay claim to the same schema.

You're example is the same as @karenetheridge's that I addressed in https://github.com/orgs/json-schema-org/discussions/198#discussioncomment-3124915. I'll try to explain in more detail.

{
  "$id": "http://example.com/ambiguous-meta-schema"
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$vocabulary": { "https://json-schema.org/draft/2020-12/vocab/core": true },
  "$ref": "https://json-schema.org/draft/2019-09/schema"
}

If we apply the draft-07 rules, we see "$schema": "https://json-schema.org/draft-07/schema#" and we know this is a draft-07 schema.

If we apply the 2020-12 rules, we have to look at the https://json-schema.org/draft-07/schema schema in order to determine which spec version to use for this schema. That schema does not have a $vocabulary keyword and therefore, the spec version to use for the original schema is unknown.

Therefore, the schema is unambiguously a draft-07 schema.

What if someone uses this schema as a meta-schema?

{
  "$id": "https://example.com/my-schema",
  "$schema": "http://example.com/ambiguous-meta-schema",
  ...
}

http://example.com/ambiguous-meta-schema is not associated with a known spec version, so no spec version draft-07 or lower is going to claim this schema.

The 2019-09 or 2020-12 specs say that we should look at the meta-schema to determine which spec version to use for this schema. We have determined that the meta-schema is a draft-07 schema, so even tho it has a $vocabulary keyword that declares the 2020-12 core vocabulary, that declaration is ignored because $vocabulary is not a draft-07 keyword. Therefore, the spec version to use to interpret the schema is unknown.

None of the spec versions claim this schema so at this point you can use a heuristic to guess or refuse the schema.

[awwright]

@jdesrosiers Ok. I don't think it's the case that you can unambiguously combine the drafts together like you're suggesting (that there's going to have to be some cases where someone's use case is going to break). This may be because of the use cases I'm trying to support and I'm working on putting together some comprehensive examples.

[awwright]

@jdesrosiers Could you speak specifically to my example where I implement only 2020-12?

The issue in this case isn't backwards compatibility or properly handing any current schema, I doubt anyone in the wild has written something like that.

But it seems that later on, some implementations will recognize draft-07, and other implementations will not; so even though both may be up-to-date, their behavior will still be different. So someone might be able to write a schema that only works on one of those implementations, and exploit this.

[jdesrosiers]

Could you speak specifically to my example where I implement only 2020-12?

This is not a special case. It works the same. This is a 2020-12 implementation, so it needs to look at the meta-schema to know what spec version to use. It finds the standard draft-07 meta-schema which is something the implementation doesn't support. Therefore, it needs to guess how to interpret the original schema or refuse to process it. If it guesses, there could be interoperability issues, which is why the correct behavior IMO is to refuse the schema.

[handrews]

Because of this:

The approach we are taking is to standardize only dialect identification in the media type registration
...
However, this doesn't technically work for 2019-09 and 2020-12 because it's not $schema that determines how a schema is processed, it's $vocabulary.

Can we talk about standardizing processing rules identification instead of dialect identification? The dialect is actually irrelevant except when it's the only available identifier for the processing rules. And in that case it's serving two roles rather than really being about dialect.

(I will come back and add an example about the $schema-of-meta-schema problem, and also why I think option #2 is the safest option as soon as I get some time. Which may take a few days.)

[awwright]

The dialect is actually irrelevant except when it's the only available identifier for the processing rules.

This is an important insight. It doesn't seem possible to "standardize only dialect identification".

[jdesrosiers]

I don't think it's possible to standardize "rules identification" in a way that works for past and future releases without adding a keyword that retroactively applies to past releases and pins us to a solution for future releases. Both of those things are things I'd like to avoid.

Different specifications have different methods of rules identification and future specifications may have different methods as well. That's why I think it makes sense to go one step higher and just standardize dialect identification. That allows implementations to determine rules identification based on which specifications they support and doesn't constrain our future choices either. (See https://github.com/orgs/json-schema-org/discussions/198#discussioncomment-3103803)

[awwright]

I want to make sure I understand this correctly so I asked a question below first... however I was going to suggest something like the algorithm that you posted there. As long as there is some way to determine "the core semantics have changed in an incompatible way" it doesn't have to be $schema. It can be e.g. the lack of a known core vocabulary. There's a few tweaks that I'm ironing out, but this is a much better path.

[awwright]

What we define should work for all past a future releases of JSON Schema and their existing implementations

What does this mean in technical terms? Can we come up with some examples of things that we would like to enable, that would not be possible just by referencing 2020-12?

[awwright]

So with regard to my original question: Let's come up with more specific examples that we can judge potential solutions by.

With respect to my example: If security like this is important, then at some point we're going to have to come up with a forward compatibility scheme and commit to it. That scheme can be something like "Dereference the meta-schema and check for the existence of a known core URI. If none is found, error."

Note that this does not commit meta-schemas to using $vocabulary forever. This is because we can add exceptions: "Dereference the meta-schema; if there's no $vocabulary and no $core keyword, then error." ($core being a hypothetical keyword that replaces $vocabulary).

[jdesrosiers]

Can we ensure this, even for validators that haven't been updated to the latest spec?

In the normal case, the dialect / processing rules of the schema should be identified somehow. In this case, it's probably part of a vocabulary with the "must understand" flag set to true and the schema will be rejected because it doesn't understand the new keyword.

In the unusual case that a dialect can not be determined, technically all bets are off and the client can choose to do anything including processing the schema and ignoring the new keyword. However, the more likely behavior is that clients will either be very clear about what they default to if they don't know something or better yet, just refuse to process the schema.

We could define the registration to require that a dialect is known, but I don't think that's technically compatible with older versions of the spec.

[jdesrosiers]

I don't think we can define backwards/forwards compatibility into the media type registration because past releases are not backwards/forwards compatible. That kind of thing needs to be defined in future specifications. It's an important thing that we need to discuss and solve for in the next release, but I don't think it's relevant to this discussion.

[awwright]

@jdesrosiers So what are some of your use cases? It seems to me this should enable us to do something specific, otherwise we would just write "Do something JSON Schema-like, dunno how, use your best judgement." So what are those things?

[jdesrosiers]

I want to be able to annotate JSON responses in an API context using a Link header with a "describedby" relation.

I want a validator implementations that enable fetching schemas over HTTP to use proper web conventions. I want to reject a document that doesn't have a proper content type as not a JSON Schema document even if it happens to look like a JSON Schema document. Optionally, if the schema doesn't declare what dialect it uses, I want to be able to get that information from the media type, but I'd prefer that information is in the schema. For security reasons, I want to be able to refuse to process any schema that doesn't somehow declare its dialect. However, clients also need to be allowed to assume a dialect in certain cases like older OpenAPI specifications that don't have a dialect id to declare. This is necessary for backwards compatibility, but should be discouraged.

I want to be able to content negotiated what dialect of a schema I can handle when fetching a schema over HTTP.

There's at least one more use case that the media type is designed to support, but those are the ones I personally use.

[OR13]

I'm supportive of getting these registered... let me know how I can help.