Explain format (and content*) more clearly

[handrews]

[this is a bit stream-of-consciousness, but I wanted to get it filed because I keep forgetting- we'll clean up the ideas here on the way to PRs]

format confuses pretty much everyone. I have noticed people filing issues against various implementations complaining of imperfect enforcement (I believe @Julian has received complaints about "email", and @johandorland about "hostname", and I suspect they are not alone).

format, contentMediaType, and contentEncoding are essentially best effort validation keywords in practice. Many if not most implementations make at least some effort to validate format. I'm not sure if anything attempts that for content* as they are new (at least as part of the validation spec), and they would essentially require parsing the string encoding and media type which is potentially very expensive.

Complicating the matter for format is the fact that many of the relatively fundamental internet-related formats such as "email" and "hostname" are very old, and conformance to specifications is rather complicated.

For "hostname", RFC 1034 forbids leading digits, but this is sometimes ignored in practice, leading to ambiguous overlap with "ipv4" as a format. In practice, most programs that accept hostnames will also accept ipv4 addresses and just recognize that no DNS resolution is required, so this is rarely a concern.

The difficulty of validating email addresses, even on the syntactical level, is well-documented (try finding a regular expression that will do it, for instance, and if you find an actual iron-clad one, let me know).

---

Leveraging our relatively recent keyword classification work, I think it is best to classify these primarily as annotations rather than treating them as some sort of hybrid annotation+assertion. Annotations can specify any intent, including semantic validation or parsing instructions. The specification should provide guidance on how an implementation might directly offer handlers for such intents, and how to indicate the available level of support.

Applications can, as with any annotation, then perform additional processing if the implementation either does not offer any validation, or offers only incomplete validation. The spec already says that implementations SHOULD offer an ability to turn semantic validation off, so we can extend that guidance (probably at the MAY level) to cover situations like allowing hooks for application-defined processing in addition to or in place of implementation-supplied validation.

And of course, all of this is dependent on an implementation supporting annotations. As with the additionalProperties and additionalItems keywords (now in the core spec and defined in terms of annotation collection), the spec should allow for the existing sort of implementations to continue to be valid and in conformance for implementations that do not implement general annotation collection support.

[johandorland]

The spec could make it even clearer that format is on a best effort only as almost every RFC it mentions is a bottomless pit of complexity. Having said that end users rarely read the JSON schema RFC and format is a pretty useful tool to have to validate common patterns, which is why it gets implemented fairly often. If you move this responsibility from the implementation to an application it makes JSON schema less powerful and puts an extra burden on the developer. The current situation where we get bug reports about not strictly implementing some archaic 1990's RFC is annoying, but it's not that bad.

As for contentMediaType and contentEncoding I agree. The scope of those two is just too broad and way broader than format and basically impossible to properly implement for validation purposes. Sure it's not that hard to check if a base64 encoded string is valid application/json, but I hope nobody expects it's JSON schema implemention to verify whether something is indeed a properly encoded WebM video.

[handrews]

@johandorland for format, I need to figure out the right wording as "the application" could actually just be a set of plugins (or even built-in code) that are part the implementation. They don't have to be literally part of the application that uses the implementation. Many implementations support format via plugins already. Mostly, I want to encourage:

1. Plugins over hardcoding, unless of course someone wants to optimize the heck out of it
2. A formal recommendation that allows for multiple levels of validation, so the implementation may, for example, only "validate" email addresses to the extent of making sure they contain an @ character (this is what the most popular Python implementation actually does, btw), but also allow a 3rd party (application or otherwise) to register additional validation logic. To whatever degree that they want.

I want it to be easier for implementation authors to say "yes, we implement it up to this point, but if you want more you can add it easily".

[johandorland]

@handrews In that case we're on the same line. It's how I interpreted the spec already, but after reading up a bit I can imagine not everyone does.

[handrews]

@johandorland thanks, this will all help make the wording more clear!

[Relequestual]

clearer*
Someone hasn't had their coffee yet huh?
(I'll actually read this tomorrow!)

[gregsdennis]

I like the idea of supporting validation for these loose keywords via "plugins." It's not something I had considered. It'll be available in my next version!

[Relequestual]

On the topic of email regex, ya'll gotta read https://www.regular-expressions.info/email.html

On the topic of this issue:
Yeah. I really like the way ajv allows you to add or replace format validation. Explicitly stating that the application MAY do that gives people the notion it could be a good idea. Great!

[gregsdennis]

I'm surprised that no one's mentioned #563 yet. Seems pertinent to me.

I think implementations allowing their clients to append/modify the format validation that is available is the way to go. I'm taking a page from ajv's book and opening up the format validation so that, while I provide some stock validations, my client can define their own or even override the ones I have to suit their specific needs.

[handrews]

@gregsdennis if you have any concerns on the implementation requirement wording around content* or format, please add them here. I'm going to review those sections based on this issue after all of the new feature PRs are done (or at least submitted).