JSON Schema At Home in the OpenAPI Specification - Core Concepts, Vocabularies, and Drafts for 2020

Recording: https://www.youtube.com/watch?v=_kNLrpce_lg

OpenAPI 3.1.0 will bring full support for JSON Schema 2019-09 (hopefully 2020-NN).

Draft 2019-09 represents the culmination of many years of work by the core team and the wider community.
I'll go over some of the core foundational concepts of JSON Schema, briefly discuss 2019-09 / 2020-NN new features, and explain why the Vocabularies concept is key for extensibility beyond validation.

Transcript

1. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema At Home in the OpenAPI Specification Core concepts, Vocabularies, and drafts for 2020 🧔 Ben Hutton 💻 @relequestual on the internet 💼 JSON Schema core team lead 🙌 opencollective.com/json-schema 🐱💻‍ github.com/sponsors/relequestual ☕ buymeacoffee.com/relequestual 🎤 ASC 2020 - API Specification Conference
2. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema?
3. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema! Fully from 3.1.0
4. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals JSON what now? From 3-hour workshop to 3 slides
5. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals – JSON Schema is… • Still JSON • An Object or a Boolean • Provides validation and annotation results • Supports extensibility • Used beyond validation (UI generation, code generation – not part of the standard) • Baked into VS Code – Provides autocomplete and annotation for config files
6. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals - Key Terminology • Root Schema • Subschema • Instance • Meta-Schema
7. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals - Validation • Root Schema • Subschema • Instance • Meta-Schema Validation keywords applicable to… • Numeric instances • Strings • Arrays • Objects • Other? (draft 2020-NN)
8. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals - Keyword behaviors • Root Schema • Subschema • Instance • Meta-Schema Validation keywords applicable to … • Numeric instances • Strings • Arrays • Objects Keyword behaviors… • Applicability • Assertion • Annotation
9. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals - Structure and Reuse • Root Schema • Subschema • Instance • Meta-Schema Validation keywords applicable to… • Numeric instances • Strings • Arrays • Objects Keyword behaviors… • Applicability • Assertion • Annotation Structure • References using URI resolution • "$ref", "$anchor", and "$id" – JSON Schema Resource • Dynamic anchor* – Complex cross resource reuse … makes creating extensions much easier! * "$recursiveAnchor" in 2019-09, "$dynamicAnchor" in 2020-NN
10. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Dialects And vocabularies! (meta-schemas only)
11. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Vocabularies – An Example Keys are URIs As with "$id", these are not necessarily network addressable. "The nature of the retrievable resource is currently undefined, and reserved for future use."
12. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Vocabularies – An Example Value indicates if support is required or optional Keys are URIs As with "$id", these are not necessarily network addressable. "The nature of the retrievable resource is currently undefined, and reserved for future use."
13. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Dialects and Vocabularies • A JSON Schema "Dialect" is a collection of vocabularies • A JSON Schema "Vocabulary" is a related collection of keywords packaged for use • Vocabularies enable extensions to JSON Schema (beyond validation) • "$vocabulary" identifies required and optional vocabulary support via meta-schema • URI for a Vocabulary and associated meta-schema will always be different • You only care about these keywords if you're • Writing an implementation • Defining an extension to JSON Schema
14. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Reuse using "$ref"
15. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "$ref" References are better now "$ref" not allowed to play with others (All other properties ignored) "$ref" is grown up now and can play with others (Other properties not ignored) You still shouldn't duplicate keys of an object. That's JSON.
16. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotation Collection Annotations, Errors, and Output
17. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotations, Errors, and Output 'draft-7' users: "I can see validation fails, but I'd like more detailed information." "I have an error message, but I can't see where it comes from." "I'd like to apply the default values to the data." "Can I get some information on why validation passed?" Us: "errr, that would depend on the implementation…. Sorry."
18. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotations, Errors, and Output 'draft 2019-09': Standard Output • Flag - A Boolean which simply indicates the overall validation result with no further details. • Basic - Provides validation information in a flat list structure. • Detailed - Provides validation information in a condensed hierarchical structure based on the structure of the schema. • Verbose - Provides validation information in an uncondensed hierarchical structure that matches the exact structure of the schema.
19. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotations, Errors, and Output 'draft 2019-09': Standard Output "But won't that require a bit of extra work for implementations?" Use of 'unevaluated*' keywords will require annotation collection.
20. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotations, Errors, and Output 'draft 2019-09': Standard Output – Flag
21. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotations, Errors, and Output 'draft 2019-09': Standard Output – Basic Contains: • overall 'valid' assertion • 'errors' array Locations are JSON Pointers
22. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotations, Errors, and Output 'draft 2019-09': Standard Output – Detailed and Verbose • More detailed • Hierarchical • "Detailed" contains only what is most likely to be useful • "Verbose" returns all results
23. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "$id" and "$anchor"
24. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "$id" • Embedding a schema inside another schema is a common concern • Creating a single schema out of many small ones • Used at the root of a schema to identify itself • Previously could be a plain name fragment in subschemas • SHOULD NOT contain an empty fragment • MUST NOT contain a non-empty fragment http://json-schema.org/draft/2019-09/json-schema-core.html#idExamples Further reading in the 2019-09 core spec: "canonical URI" and Core Appendix A
25. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "$anchor" • Use "$anchor" for plain name fragment subschema identification • Allows transcluded (or bundled) schemas with relative references to continue to function as expected, rather than potentially breaking
26. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Transcluded JSON Schema Resources … actually, for draft 2020-NN, some clarifications… • Embedding a Schema RESOURCE in another Schema, we now call "creating a schema bundle" or a "compound JSON Schema document" • "$id" in the non-root Schema signifies an "embedded Schema Resource" • Identification of embedded Schema Resources allows for cross version (and cross dialect) schema bundling • Validating a Schema is valid cannot always be done by applying the meta-schema to the Schema as an instance!
27. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "unevaluated*"
28. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "unevaluatedProperties" • Value must be a Schema • Value Schema is applied to child values of instance names that have not been evaluated (annotation collection) • "seeing through" applicator keywords • Annotation collection support required, or must raise an error
29. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "unevaluatedProperties" Instance data is of a patient, which is made up of schemas "patient" and "person". These could be external references. "unevaluatedProperties" is similar to "additionalProperties" Value schema is applied based on the annotation collection of specific keywords (which must be done first). "name" and "age" from "person", and "patientID" and "patientDetails" from patient, will have annotations. Other keys in the instance object will cause validation failure This schema is not quite right…
30. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "unevaluatedProperties" – A problem? Works similar to "additionalProperties", which is not effected by "required". "unevaluatedProperties" is only effected by annotation results from "properties", "patternProperties", "additionalProperties", or "unevaluatedProperties". Must add "properties" where the keys include "name" and "age" to the person schema. (The values may simply be `true`) Note: Cannot see "up" the tree!
31. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Beyond? What's next for JSON Schema?
32. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev 2019-09 - 2020-NN and beyond • "Very soon" draft 2020-NN for OpenAPI 3.1 • Small update based on work originally for 2020-NN • Update test suite • Educational resources • Triage of all open issues Nice to haves… • Official linter tooling • Define a clear path to standardisation adoption • Multiple possible paths are available
33. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Where do I go?
34. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Where to go Basics: json-schema.org/learn More info: json-schema.org/understanding-json-schema Playground: jsonschema.dev (draft-07 only for now) Help: stackoverflow.com (and tag with `jsonschema`) More help: json-schema.org – Click "Join our Slack"
35. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Thank you all • Previous and current team • Contributors and community • Implementation developers • all of you
36. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema At Home in the OpenAPI Specification Core concepts, Vocabularies, and drafts for 2020 Thank you sponsors! AsyncAPI Initiative Stoplight 🧔 Ben Hutton 💻 @relequestual on the internet 💼 JSON Schema core team lead 🙌 opencollective.com/json-schema 🐱💻‍ github.com/sponsors/relequestual ☕ buymeacoffee.com/relequestual 🎤 ASC 2020 - API Specification Conference Retool