✨ Proposal: `recommended` keyword similar to `required`

[juanmeleiro]

Describe the inspiration for your proposal

I write JSON by hand to store data in lots of my personal projects. Two illustrative examples are keeping journals and storing metadata about books and other media I have in my library. I also use JSON Schemas to make sure I don't mistype anything, and I don't forget any fields.

However, I found in more than one occasion that some fields are not strictly necessary, but are almost always used and their omission almost always is a mistake. This is precisely the semantics of the “SHOULD” keyword such as in RFC 2119 and similar documents.

To my mind, the best behavior a schema checker should have in this situations is to issue a warning (not an error) upon the omission of such a keyword.

Alas, I could not find a feature of JSON schema that would have checkers in the wild issue warnings.

Describe the proposal

I see two possibilities:

• Add a keyword recommended to object schemas that would have as a value a list of strings. Those strings are keys that SHOULD be present in objects to be matched by the schema, and checkers SHOULD issue a warning if not present.

• Add a keyword recommended to any schema that would take as a value another schema. If this child schema does not match, then checkers SHOULD issue a warning.

Describe alternatives you've considered

I can't figure out a way to do this with existing checkers and vocabularies. There might be a vocabulary with this feature (or one might be created), but that would require (as far as I understand) extending any single checker with support for that vocabulary.

Additional context

I'm new to this project and I understand that my suggestion my go against some design goal or policy, in which case I understand it might get rejected out of the gate.

[jdesrosiers]

That's an interesting idea. The problem is that JSON Schema currently doesn't have concept of a keyword producing a warning. Keywords produce a validation result (true/false) and/or an annotation. So, this keyword would have to produce an annotation that can then be used by some sort of post-processing step like an editor producing a warning. So, I think that means it's not a great fit for the validation spec. It sounds like a something that could be a vocabulary defined for some purpose other than validation.

[SatyamKumarCS]

Hi,
I’m interested in taking this issue forward and implementing the required changes.
Please assign it to me when possible.
Thanks!

[karenetheridge]

Validation is a formalized concept in the specification, but linting is not. If we had that, then this keyword could be part of that effort. But I think we'd have to do a lot of work in describing what a linter should do and what sort of data it would emit, and what we expect implementations to do in the normal case.

[jdesrosiers]

@SatyamKumarCS, please take more care when volunteering to be assigned an issue. This issue is clearly not ready to be assigned to anyone and is not likely to go forward due to the issues I described in my previous comment. Now is the time for making the case for why the feature should be added and discussing how it would work. If you want to contribute here, you can participate in that discussion.

In any case, spec writing requires expert knowledge of JSON Schema, the specifications it references, and the community. Although we want to hear voices from all levels in discussion, we only assign the actual spec writing to people who have demonstrated they have the necessary expertise and experience.

[juanmeleiro]

The objections make sense. It does seem like a lot of work for a minor feature, and the spec should probably be kept simpler rather than more complex, to my mind. Perhaps annotations do indeed offer an alternative. I'll look into it.