LF_APIStrat17_Embracing JSON Schema

Proprietary + Confidential
Embracing JSON Schema
Jeremy Whitlock (@whitlockjc)

Source: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis non erat sem
What is JSON Schema?

“JSON Schema is a vocabulary that allows you to
annotate and validate JSON documents.”
http://json-schema.org

“JSON Schema is a language-agnostic
description format for data structures, their
constraints and relationships.”
Jeremy Whitlock

Simplicity Readability Language Agnostic
JSON is essentially a simple way to
represent a dict/map/… of key/value
pairs, where the values can be 1 of 6
types.
The same JSON representation is
easily consumed by humans and
machines alike.
Most languages have native support
for JSON and/or a plethora of libraries
for consuming/producing JSON.
JSON Schema

Actual Historical Photo*
{
"message": "Ron was here!"
}
* Not really

Description Relationships/Reuse Constraints/Validation
JSON Schema provides everything
necessary to describe data structures
regardless of their complexity.
Understanding the relationships of
more complex data structures is easy
using JSON Schema.
The same document describing your
data structures can contain
constraints that will be used by JSON
Schema libraries to do validation for
you.
JSON Schema

JSON Schema Example

JSON Schema Example
{
"title": "Submit APIStrat proposal",
"completed": true
}
TO BE CONTINUED...

Disclaimer
All JSON Schema examples are in JSON but DO
NOT get too stuck on the JSON bit, JSON is not
required. In fact, anything that could be converted
to a JSON representation would work. For
example, YAML or a Go struct or Java Beans...

JSON Schema
{ }

$schema id
Used to identify the document as a
JSON Schema document, this property
value is a URL to the JSON Schema
standard your document will be using.
Used to uniquely identify your JSON
Schema document, this property value
is a URL to where your JSON Schema
document will be served. (This value
has an impact on reuse, discussed
later.)
JSON Schema - Document Metadata

JSON Schema Example
{
"$schema": "http://json-schema.org/schema#",
"id": "http://example.com/schemas/todo.json"
}

JSON Schema - Types
simple complex
● boolean
● integer*
● null
● number
● string
● array
● object
* Not a JSON type, specific to JSON Schema

JSON Schema Example
{
"id": "http://example.com/schemas/todo.json",
"type": "object"
}

JSON Schema Example
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"completed": {
"type": "boolean"
}
}
}

JSON Schema - Validation
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"completed": {
"type": "boolean"
}
}
}
{
"completed": true
}
{}
{
"title": "Submit APIStrat proposal"
}
{
"title": "",
"completed": true,
"extra": [1, 2, 3]
}
[1, 2, 3]
{
"completed": "yes"
}

JSON Schema - Constraints and Formats
Constraints Formats
Used to apply limitations or
restrictions on the value represented in
the JSON Schema. For example,
restricting the maximum number of
characters in a string value.
Used to indicate the value is a more
specialized version of the specified
type. For example, indicating that a
string value is an email address.

JSON Schema Example
{
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 32
"minLength": 3
},
"completed": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": ["title", "completed"]
}

{
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 32
"minLength": 3
},
"completed": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": ["title", "completed"]
}
{
"completed": true
}
{}
{
"title": "Submit APIStrat proposal"
}
{
"title": "",
"completed": true,
"extra": [1, 2, 3]
}
[1, 2, 3]
{
"completed": "yes"
}

* Not really

JSON Schema - Reuse
Composition Definitions References
Combining multiple separate schemas
into one, more complex schema.
There is a convention that if your
JSON Schema document has multiple
schemas in it, you nest them within a
root property named "definitions" and
use references to them.
Pointers to other schemas, whether in
the same document or in another
document, to avoid duplication.

JSON Schema - Definitions
The definitions property at the root
of a JSON Schema document is a
key/value pair where the key is the
human-friendly name of the schema
and the value is a schema.
{
"id": "http://example.com/schemas/todo-types.json",
"definitions": {
"Password": {
"type": "string",
// Omitted for brevity
},
"User": {
"type": "object",
},
"Todo": {
"type": "object",
}
}
}
Yes, I know comments aren't allowed in JSON...

JSON Schema - References
References are a special JSON
object that has a $ref property in it
whose value is a JSON Pointer (URI)
to another location in the same file,
another file in its entirety or specific
location within another file.
{
"id": "http://example.com/schemas/todo-items.json",
"definitions": {
"Todo": {
"type": "object",
"properties": {
"owner": {
"$ref": "person.json"
},
"created": {
"$ref": "types.json#/definitions/Timestamp"
},
}
},
}
"type": "array",
"items": {
"$ref": "#/definitions/Todo
},
}
Yes, I know comments aren't allowed in JSON...

JSON Schema - Composition
allOf ● An array of schemas
● The data must validate against all schemas
anyOf ● An array of schemas
● The data must validate against at least one schema
oneOf ● An array of schemas
● The data must validate against only one schema
not* ● A subschema
● The data must not validate against the subschema
* not is not really a composition property but it's typically documented alongside the others

JSON Schema - Miscellaneous
Schema Metadata Default Values
The title and description properties
can be used on any schema to give it a
human readable name and description
of what the schema represents.
Sometimes your data structures have
optional values and using a default
property allows you to fill in the gaps
when the values are not provided

Using JSON Schema
● Code generation
● Contract enforcement
● Documentation generation
● Interface design

Using JSON Schema - OpenAPI

Using JSON Schema - Resources
JSON Homepage/Reference - http://www.json.org/
JSON Schema Tooling - http://json-schema.org/implementations.html
JSON Schema Homepage - http://json-schema.org/
Understanding JSON Schema Book - https://spacetelescope.github.io/understanding-json-schema/
JSON Schema Online Editor - https://jsonschema.net/#/editor

The End
No...I'm not really signing autographs. They wouldn't be worth the paper they are written on. ;)

LF_APIStrat17_Embracing JSON Schema

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to LF_APIStrat17_Embracing JSON Schema

Similar to LF_APIStrat17_Embracing JSON Schema (20)

More from LF_APIStrat

More from LF_APIStrat (20)

Recently uploaded

Recently uploaded (20)

LF_APIStrat17_Embracing JSON Schema