what is the story of "format"?

[SorinGFS]

I try to understand why format was splitted in format-annotatoon and format-asertion and why the former is the default.

Also, that documentation says:

For example, some implementations may consider a string an email if it contains a @, while others might do additional checks for other aspects of a well formed email address.

Later in the document says that "format": "email"' means RFC 5321, section 4.1.2

So what is this, a standard or a market trade?

Also, that documentation says:

In Draft 4-7, there is no guarantee that you get annotation-only behavior by default.

I don't understand what importance still has format in later drafts.

[jdesrosiers]

format was defined long before anyone involved in the project was around, so we don't know the reasons it was defined the way it was. (I'll speculate later on what I think happened.) Since then, others have tried to improve the situation, but honestly, right now we have a bit of a weird frankenstien where almost anything is allowed depending on how you configure things.

In the beginning (spec <= 2019-09), it was up to implementations to decide how or if to validate format. It's not clear why it was defined that way, but I'll give my guess a little later. As you point out, this results in different implementations producing different results. The current spec team (especially the previous lead who isn't around anymore) were not comfortable with this inconsistency and made changes in the last couple releases to try to work toward a better solution while respecting that fixing the problem would be a breaking change.

In 2019-09, format was changed to be required to not be validated by default. Users could still get the implementation defined validation behavior through implementation-specific configuration. This ensures that all implementations produce consistent results. Why not change it to require full validation instead? Mostly because format was considered so broken and untrusted that the plan was to minimize it to the point where it could be removed and if necessary replaced by something else, preferably several separate keywords.

But also, changing format to require that it strictly validate isn't as simple as it sounds. "email" is the perfect example. It turns out that mail servers tend to be more lenient than the RFC defines. People actually have email addresses that they've been using for decades that still work but don't technically conform to the RFC. The only sure way to know if an email address is valid is to send them an email and see if they receive it. That's why a lot of implementations don't do more than check if there is a @. Being more strict could mean that a customer's email address is rejected.

In 2020-12, format was split into two different vocabularies: format-annotation and format-assertion. format-annotation works the same as it did before. The default is no validation, but users can configure implementations to provide implementation-defined validation. The implementation-defined option was almost removed, but retained for sake of not breaking backward compatibility. The format-assertion vocabulary defines the full validation behavior that a lot of people expect. However, in order to use that vocabulary, they need to construct a custom dialect that uses it, which no one does.

So, you can see at this point, users have all the options. They can get strict validation, no validation, or the legacy 🤷‍♂️ validation. It's better than it was and the default behavior for both vocabularies does produce consistent results. The legacy behavior is still available, but you have to choose to use it.

---

Now, my speculation about how I think the partial/optional validation situation happened in the first place. JSON doesn't have types like Date, so in order to express a date in JSON, you need to encode it as a string. I think format originated as an annotation to declare the semantics of those string-encoded values. It says, this is a string, but you should treat it as if it's a date.

format could be used by tools that parse a JSON instance into a Java object. The parser can use "format": "date" to know that it can parse that string and emit a Date instead of the raw string. So, format isn't for validation, but it can be useful for validators to use format as well to give you a sanity check that your date will in fact parse correctly by the JSON -> Java parser. That's why partial validation is allowed, but not required. Validation is only a convenience for the schema author, so it's not important if it's not perfect.

I think that concept quickly evolved into format being something that was good for validating strings in ways where a regex either isn't sufficient or is too cumbersome to include in a schema. That's a far more useful concept and it's not surprising that that's the direction format ended up going. It probably needs to be split so both of these concepts are represented as different things. For example, a string value could be annotated as being semantically a date and at the same time specify that the string representation conforms to a specific date format.

[gregsdennis]

The format-assertion vocabulary defines the full validation behavior that a lot of people expect.

To amend this excellent answer, the format-assertion vocabulary was created specifically to allow schema authors to specify that format should be validated. Prior to this, only schema consumers had this ability because they could configure their validator to perform those assertions (schema authors don't have access to the validators their consumers use). By making the format-assertion vocabulary available, an author now has that power as well.

[SorinGFS]

@jdesrosiers

Thank you for the detailed explanation.

So, you can see at this point, users have all the options.

There is no option to have both in the same schema. We may need to annotate in some part of the schema, and validate in other part. 😄

It probably needs to be split so both of these concepts are represented as different things. For example, a string value could be annotated as being semantically a date and at the same time specify that the string representation conforms to a specific date format.

Exactly what I was saying before. And I'll add that would be better to solve this problem within next draft, since you probably don't want to have such a big issue to be inherited infinitely.

[SorinGFS]

@gregsdennis

I think this issue must be solved without the need of vocabulary.

[gregsdennis]

I think this issue must be solved without the need of vocabulary.

You asked for a history. The history is that we used a vocabulary.

[SorinGFS]

No obiection to that, I only said in addition to what you said.