Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Ben Hutton
September 17, 2020

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.

Ben Hutton

September 17, 2020
Tweet

More Decks by Ben Hutton

Other Decks in Technology

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