SHOULD accept application/json and not make application/schema+json a MUST about json-schema-core

[jdesrosiers]

After giving this a lot of thought, I want to leave the behavior as it is. However, I would be ok with adding a configuration of some sort to enable a lenient mode that would allow the implementation to process anything that it fetches as a schema.

If I put a URL in a web browser and I get back a document that has HTML, but uses a plain/text content type, I wouldn't expect it to render a web page, I'd expect to see HTML code. JSON Schema is built on top of web standards which makes implementations like this effectively a web client so it should function like a well behaved web client. In the future I might want to add support for other types of validation engines and there's no reason why you couldn't reference from a JSON Schema to something else. If I just treat everything as a JSON Schema, I couldn't support something like that.

I did consider that maybe because JSON Schema is JSON, I could accept JSON and run it through the algorithm as if it was a JSON Schema. The main problem with that is that JSON doesn't define semantics for URI fragments. That feature is added by application/schema+json. So, if I pass a JSON document through instead of a Schema document, any local references (such as #/$defs/foo), would always point to the root of the JSON document, not the location the fragment points to. Although that would be technically correct behavior in that situation, it will undoubtedly be considered a bug by anyone that comes across it.

Regarding compatibility with the JSON Schema spec, I don't think there's an issue. The spec talks about how you should serve schemas, but doesn't say anything about what clients should accept.

If this URI identifies a retrievable resource, that resource SHOULD be of media type "application/schema+json".

Here's the definition of SHOULD

SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

So, the way I interpret the JSON Schema spec is that, there may exist valid reasons in particular circumstances to not serve schemas with application/schema+json, but before using another content type you should understand that implementations might not recognize the document as a schema.

[n2ygk]

From a practical perspective, GitHub Pages does not allow one to specify a content-type of application/schema+json and instead sends application/json so examples from json-schema.org can't be $ref'd.

[jdesrosiers]

Oh, I agree that there are cases where you can't get around it. That's why I'm ok with adding a flag to allow it. I'm just not ok with it being the default behavior.

A better solution is to register the schema.json file extension so Github Pages will serve the right content-type (json-schema-org/json-schema-spec#1130). However, I'm not too worried about the examples on json-schema.org. They aren't there for people to $ref. Implementations are not expected to fetch references. You're expected to download the examples and load them into a validator locally.

[n2ygk]

At least one validator in fact does allow directly downloading the $ref: https://www.jsonschemavalidator.net/.

…

On Mon, Oct 4, 2021 at 3:10 PM Jason Desrosiers ***@***.***> wrote: Oh, I agree that there are cases where you can't get around it. That's why I'm ok with adding a flag to allow it. I'm just not ok with it being the default behavior. A better solution is to register the schema.json file extension so Github Pages will serve the right content-type ( json-schema-org/json-schema-spec#1130 <json-schema-org/json-schema-spec#1130>). However, I'm not too worried about the examples on json-schema.org. They aren't there for people to $ref. Implementations are not expected to fetch references. You're expected to download the examples and load them into a validator locally. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#9 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABBHS5436ESZFNTP46SVQFDUFH33XANCNFSM5FFKHFTQ> .

[jdesrosiers]

That's fine. Different implementations can make different decisions. Remember that fetching a schema over the network or file system is not something the specification defines. Implementations are explicitly not expected to do this. So, if they do, there are no rules about how it must be done. I chose to follow web standards closely. Others might not care. Both are allowed.

Honestly, I'm a bit surprised about the push back. Is adding a configuration flag to enable this behavior not good enough? Is it terribly important that it be the default behavior?

[ioggstream]

#9 (comment) duly noted ietf-wg-httpapi/mediatypes#7

[jdesrosiers]

I added support for custom media type handlers. If you want to configure it to assume plain JSON is a JSON Schema you can do this,

JsonSchema.addMediaTypePlugin("application/json", {
  parse: async (response) => await response.json(),
  matcher: (path) => path.endsWith(".json")
});

Or, if you want absolutely anything to be assumed to be a JSON Schema you can do this,

JsonSchema.addMediaTypePlugin("application/octet-stream", {
  parse: async (response) => await response.json(),
  matcher: (path) => true
});