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
   

   View Slide

2. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
   JSON Schema?
   

   View Slide

3. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
   JSON Schema!
   Fully from 3.1.0
   

   View Slide

4. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
   Fundamentals
   JSON what now?
   From 3-hour workshop to 3 slides
   

   View Slide

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
   

   View Slide

6. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
   Fundamentals - Key Terminology
   • Root Schema
   • Subschema
   • Instance
   • Meta-Schema
   

   View Slide

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)
   

   View Slide

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
   

   View Slide

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
   

   View Slide

10. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    Dialects
    And vocabularies!
    (meta-schemas only)
    

    View Slide

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."
    

    View Slide

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."
    

    View Slide

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
    

    View Slide

14. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    Reuse using "$ref"
    

    View Slide

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.
    

    View Slide

16. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    Annotation Collection
    Annotations, Errors, and Output
    

    View Slide

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."
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

20. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    Annotations, Errors, and Output
    'draft 2019-09': Standard Output – Flag
    

    View Slide

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
    

    View Slide

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
    

    View Slide

23. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    "$id" and "$anchor"
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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!
    

    View Slide

27. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    "unevaluated*"
    

    View Slide

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
    

    View Slide

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…
    

    View Slide

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!
    

    View Slide

31. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    Beyond?
    What's next for JSON Schema?
    

    View Slide

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
    

    View Slide

33. #ASC2020 – Ben Hutton @relequestual – JSON Schema core – jsonschema.dev
    Where do I go?
    

    View Slide

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"
    

    View Slide

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
    

    View Slide

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
    

    View Slide