Consider "API best practices" section

[awwright]

There should be a section with guidelines for how to write a validator API. The section would be informative (non-normative), on observations on how to best expose the functionality that JSON Schema offers for validation and forward-compatibility.

Topics would include (feel free to edit list/suggest edits):

• How to import multiple schemas that refer to each other
  • Implementations should offer some sort of collection or registry that schemas are imported to, specifying the URI they were retrieved from.
• How to report informative and localizable error messages
  • Validators should report the keyword that caused the validation failure, and software should rely on this for writing its own error messages. This might be a property associated with the error, or validators might subclass a ValidationError class, one for each JSON Schema keyword.
  • Validators should also report a full error message, intended for debugging.
• How to report lists of errors
• Consider supporting as many old features as possible, and report on deprecated feature usage
• How to list non-fatal warnings while processing the schema
• Offer different validation reporting modes, e.g. stop at first validation failure, or collect as many as possible
• How to report errors for complex rules like "oneOf" or "not"
  • Try and find the smallest change that would cause validation to pass, and suggest making that.
• How to handle custom vocabulary and add custom assertions/keywords
  • Allow software to register a callback that handles a given keyword
• How to handle unknown keywords (offer option to report as fatal error, or warning, or ignore)
• ... and how to handle custom vocabulary that requires asynchronous I/O
• Offer options for relaxing rules, e.g.
  • precision of floating point numbers if numbers are cast to IEEE floating points
  • handling of null
• Offering options to patch third-party schemas, e.g.
  • add maxLength properties to most strings because of local implementation memory constraints
• Offering options to cast certain schemas to native objects at parse-time, e.g.
  • casting certain string properties to native Date objects

[carlosaq]

Does any know if there are something ready or only will be start to define?

[awwright]

@carlosaq I'm not sure what you're asking.

[handrews]

@awwright a lot of these things are things that already have issues filed to be resolved as part of the spec work. There should not be an overlap between that and any best practices document work. Some covered by #314 and related issues, others by issues tagged with the "output" label.

Even considered as best practices, this is a large grab-bag of different things. Can we

a.) whittle this down to things that aren't being addressed, and should not be addressed, elsewhere b.) organize this a bit- there are several different kinds of implementation advice c.) figure out a heuristic for what really needs to be in a spec appendix and what should go on the web site

[gregsdennis]

Try and find the smallest change that would cause validation to pass, and suggest making that.

That's some heavy-duty analysis.

Overall I like the idea of this. Manatee.Json already supports many of these. I'd be happy to provide examples of how it's implemented to give some direction.

As @handrews mentioned, I know we already have issues for some of these. https://github.com/json-schema-org/json-schema-spec/issues/396 comes to mind immediately.