JSON Schema - draft 2020 and other things you should know

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

Learn about JSON Schema draft 2020-12

Transcript

1. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema Draft 2020 and other things you SHOULD know 🧔 Ben Hutton 💻 @relequestual on the internet 💼 JSON Schema core team lead 🙌 opencollective.com/json-schema 🐱💻‍ github.com/sponsors/relequestual ☕ buymeacoffee.com/relequestual 🎤 apidays Paris 2020
2. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema?
3. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema! Fully from 3.1.0
4. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals JSON what now? From 3-hour workshop to 3 slides
5. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev 🎉 JSON Schema draft 2020-12 released! draft-bhutton-json-schema-00 draft-bhutton-json-schema-validation-00 Website updates pending But you can use it today! - @hyperjump/json-schema
6. apidays Paris 2020 – 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
7. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Fundamentals - Key Terminology • Root Schema • Subschema • Instance • Meta-Schema
8. apidays Paris 2020 – 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-12)
9. apidays Paris 2020 – 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
10. apidays Paris 2020 – 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-12
11. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Dialects And vocabularies! (meta-schemas only)
12. apidays Paris 2020 – 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."
13. apidays Paris 2020 – 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." "Fixed" in 2020-12
14. apidays Paris 2020 – 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
15. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev "$ref" 2019-09 and onwards
16. apidays Paris 2020 – 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.
17. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Annotation Collection Annotations, Errors, and Output
18. apidays Paris 2020 – 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."
19. apidays Paris 2020 – 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.
20. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev What's new for draft 2020-12?
21. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema draft 2020-12 • Published 2 days ago! • Meta-Schema coming (mostly done) • Tests in progress • Update website and docs • Part of OAS 3.1.0 release (pretty sure) • You can read the specification TODAY! `draft-bhutton-json-schema-00` and `draft-bhutton-json-schema-validation-00` • You can use it today! - @hyperjump/json-schema
22. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema draft 2020-12 • Compound Schema Documents • `items` and `prefixItems` • `format` split into annotation only and assertion vocabulary • Updated regular expression support (ECMA-262 11th edition - Unicode) • Rename and enhance `$recusive*` to `$dynamic*` (Advanced meta- schema usage)
23. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Compound Schema Documents
24. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev 2012-12 - Bundled JSON Schema Resources Clearly defined for draft 2020-12 • 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
25. apidays Paris 2020 – 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 This construct is no longer valid
26. apidays Paris 2020 – 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
27. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev `items` and `prefixItems` Less footguns
28. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev 2020-12 -`items` and `prefixItems` `items` • Single value schema only • Applied subschema to all items in the array (after prefix items) `prefixItems` • Array value schemas only (tuple form) • Applies subschemas to the item which matches the same index draft 2019-09 draft 2020-12
29. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev `format` vocabularies Predictable behaviour
30. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev 2020-12 `format` • Draft 2019-09 and prior: "format" might do some validation… but that totally depends on the implementation… unpredictable! • Draft 2020-12: "format" is an annotation only, and doesn't provide validation… Predictable behaviour!
31. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev 2020-12 `format` • `format` is now in two vocabularies • Annotation only version is included in standard dialect • Assertion (validation) version is not included in any dialect • We (or others) may publish a dialect which requires the assertion `format` vocabulary
32. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Where do I go?
33. apidays Paris 2020 – 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"
34. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev Thank you all • Previous and current team • Contributors and community • Implementation developers • all of you Pictures thanks to @bit_loom
35. apidays Paris 2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev JSON Schema Draft 2020 and other things you SHOULD know 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 🎤 apidays Paris 2020 Retool