diff --git a/.travis.yml b/.travis.yml index 12841e3a..205d3479 100644 --- a/.travis.yml +++ b/.travis.yml @@ -8,18 +8,4 @@ before_script: - PATH="./node_modules/.bin/:$PATH" script: - bundle exec jekyll build -- ajv test -s schema -d "_includes/person.json" --valid -- ajv test -s schema -d "_includes/example1/schema*.json" --valid -- ajv test -s _includes/example1/schema1.json -d _includes/example1/instance.json --valid -- ajv test -s _includes/example1/schema2.json -d _includes/example1/instance.json --valid -- ajv test -s _includes/example1/schema3.json -d _includes/example1/instance.json --valid -- ajv test -s _includes/example1/schema4.json -d _includes/example1/instance.json --valid -- ajv test -s _includes/example1/schema5.json -d _includes/example1/instance.json --valid -- ajv test -s schema -d _includes/example1/set_schema.json --valid -- ajv test -s _includes/example1/set_schema.json -d _includes/example1/set_instance.json -r geo --valid -- ajv test -s schema -d "_includes/example2/schema*.json" --valid -- ajv test -s schema -d "_includes/example2/entry_schema*.json" --valid -- ajv test -s schema -d "_includes/example2/storage_schema*.json" --valid -- ajv test -s _includes/example2/schema1.json -d _includes/example2/instance.json --valid -- ajv test -s _includes/example2/schema2.json -d _includes/example2/instance.json -r _includes/example2/entry_schema3.json --valid -- ajv test -s schema -d address -d calendar -d card -d geo --valid \ No newline at end of file +- ajv test -s schema -d "learn/examples/*.json" --valid diff --git a/_config.yml b/_config.yml index 7bcc4ec8..d5aeeab0 100644 --- a/_config.yml +++ b/_config.yml @@ -28,7 +28,7 @@ theme: minima header_pages: - specification.md -- examples.md +- learn/index.md - implementations.md exclude: diff --git a/_includes/example1/instance.json b/_includes/example1/instance.json deleted file mode 100644 index 3cf40ec6..00000000 --- a/_includes/example1/instance.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "id": 1, - "name": "A green door", - "price": 12.50, - "tags": ["home", "green"] -} \ No newline at end of file diff --git a/_includes/example1/schema1.json b/_includes/example1/schema1.json deleted file mode 100644 index bde74825..00000000 --- a/_includes/example1/schema1.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "Product", - "description": "A product from Acme's catalog", - "type": "object" -} \ No newline at end of file diff --git a/_includes/example1/schema2.json b/_includes/example1/schema2.json deleted file mode 100644 index 593db4ce..00000000 --- a/_includes/example1/schema2.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "Product", - "description": "A product from Acme's catalog", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier for a product", - "type": "integer" - } - }, - "required": ["id"] -} \ No newline at end of file diff --git a/_includes/example1/schema3.json b/_includes/example1/schema3.json deleted file mode 100644 index cd8e32fd..00000000 --- a/_includes/example1/schema3.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "Product", - "description": "A product from Acme's catalog", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier for a product", - "type": "integer" - }, - "name": { - "description": "Name of the product", - "type": "string" - } - }, - "required": ["id", "name"] -} \ No newline at end of file diff --git a/_includes/example1/schema4.json b/_includes/example1/schema4.json deleted file mode 100644 index 5d0a5490..00000000 --- a/_includes/example1/schema4.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "Product", - "description": "A product from Acme's catalog", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier for a product", - "type": "integer" - }, - "name": { - "description": "Name of the product", - "type": "string" - }, - "price": { - "type": "number", - "exclusiveMinimum": 0 - } - }, - "required": ["id", "name", "price"] -} \ No newline at end of file diff --git a/_includes/example1/schema5.json b/_includes/example1/schema5.json deleted file mode 100644 index c17d9db2..00000000 --- a/_includes/example1/schema5.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "Product", - "description": "A product from Acme's catalog", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier for a product", - "type": "integer" - }, - "name": { - "description": "Name of the product", - "type": "string" - }, - "price": { - "type": "number", - "exclusiveMinimum": 0 - }, - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "uniqueItems": true - } - }, - "required": ["id", "name", "price"] -} \ No newline at end of file diff --git a/_includes/example1/set_instance.json b/_includes/example1/set_instance.json deleted file mode 100644 index b847cede..00000000 --- a/_includes/example1/set_instance.json +++ /dev/null @@ -1,31 +0,0 @@ -[ - { - "id": 2, - "name": "An ice sculpture", - "price": 12.50, - "tags": ["cold", "ice"], - "dimensions": { - "length": 7.0, - "width": 12.0, - "height": 9.5 - }, - "warehouseLocation": { - "latitude": -78.75, - "longitude": 20.4 - } - }, - { - "id": 3, - "name": "A blue mouse", - "price": 25.50, - "dimensions": { - "length": 3.1, - "width": 1.0, - "height": 1.0 - }, - "warehouseLocation": { - "latitude": 54.4, - "longitude": -32.7 - } - } -] \ No newline at end of file diff --git a/_includes/example1/set_schema.json b/_includes/example1/set_schema.json deleted file mode 100644 index 93366142..00000000 --- a/_includes/example1/set_schema.json +++ /dev/null @@ -1,44 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "Product set", - "type": "array", - "items": { - "title": "Product", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier for a product", - "type": "number" - }, - "name": { - "type": "string" - }, - "price": { - "type": "number", - "exclusiveMinimum": 0 - }, - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "uniqueItems": true - }, - "dimensions": { - "type": "object", - "properties": { - "length": {"type": "number"}, - "width": {"type": "number"}, - "height": {"type": "number"} - }, - "required": ["length", "width", "height"] - }, - "warehouseLocation": { - "description": "Coordinates of the warehouse with the product", - "$ref": "http://json-schema.org/geo" - } - }, - "required": ["id", "name", "price"] - } -} \ No newline at end of file diff --git a/_includes/example2/entry_schema1.json b/_includes/example2/entry_schema1.json deleted file mode 100644 index d6c7beff..00000000 --- a/_includes/example2/entry_schema1.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "id": "http://some.site.somewhere/entry-schema#", - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "schema for an fstab entry", - "type": "object", - "required": [ "storage" ], - "properties": { - "storage": { - "type": "object", - "oneOf": [ - { "$ref": "#/definitions/diskDevice" }, - { "$ref": "#/definitions/diskUUID" }, - { "$ref": "#/definitions/nfs" }, - { "$ref": "#/definitions/tmpfs" } - ] - } - }, - "definitions": { - "diskDevice": {}, - "diskUUID": {}, - "nfs": {}, - "tmpfs": {} - } -} \ No newline at end of file diff --git a/_includes/example2/entry_schema2.json b/_includes/example2/entry_schema2.json deleted file mode 100644 index 50dfc582..00000000 --- a/_includes/example2/entry_schema2.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "id": "http://some.site.somewhere/entry-schema#", - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "schema for an fstab entry", - "type": "object", - "required": [ "storage" ], - "properties": { - "storage": { - "type": "object", - "oneOf": [ - { "$ref": "#/definitions/diskDevice" }, - { "$ref": "#/definitions/diskUUID" }, - { "$ref": "#/definitions/nfs" }, - { "$ref": "#/definitions/tmpfs" } - ] - }, - "fstype": { - "enum": [ "ext3", "ext4", "btrfs" ] - }, - "options": { - "type": "array", - "minItems": 1, - "items": { "type": "string" }, - "uniqueItems": true - }, - "readonly": { "type": "boolean" } - }, - "definitions": { - "diskDevice": {}, - "diskUUID": {}, - "nfs": {}, - "tmpfs": {} - } -} \ No newline at end of file diff --git a/_includes/example2/entry_schema3.json b/_includes/example2/entry_schema3.json deleted file mode 100644 index 5ae25a98..00000000 --- a/_includes/example2/entry_schema3.json +++ /dev/null @@ -1,83 +0,0 @@ -{ - "id": "http://some.site.somewhere/entry-schema#", - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "schema for an fstab entry", - "type": "object", - "required": [ "storage" ], - "properties": { - "storage": { - "type": "object", - "oneOf": [ - { "$ref": "#/definitions/diskDevice" }, - { "$ref": "#/definitions/diskUUID" }, - { "$ref": "#/definitions/nfs" }, - { "$ref": "#/definitions/tmpfs" } - ] - }, - "fstype": { - "enum": [ "ext3", "ext4", "btrfs" ] - }, - "options": { - "type": "array", - "minItems": 1, - "items": { "type": "string" }, - "uniqueItems": true - }, - "readonly": { "type": "boolean" } - }, - "definitions": { - "diskDevice": { - "properties": { - "type": { "enum": [ "disk" ] }, - "device": { - "type": "string", - "pattern": "^/dev/[^/]+(/[^/]+)*$" - } - }, - "required": [ "type", "device" ], - "additionalProperties": false - }, - "diskUUID": { - "properties": { - "type": { "enum": [ "disk" ] }, - "label": { - "type": "string", - "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$" - } - }, - "required": [ "type", "label" ], - "additionalProperties": false - }, - "nfs": { - "properties": { - "type": { "enum": [ "nfs" ] }, - "remotePath": { - "type": "string", - "pattern": "^(/[^/]+)+$" - }, - "server": { - "type": "string", - "oneOf": [ - { "format": "hostname" }, - { "format": "ipv4" }, - { "format": "ipv6" } - ] - } - }, - "required": [ "type", "server", "remotePath" ], - "additionalProperties": false - }, - "tmpfs": { - "properties": { - "type": { "enum": [ "tmpfs" ] }, - "sizeInMB": { - "type": "integer", - "minimum": 16, - "maximum": 512 - } - }, - "required": [ "type", "sizeInMB" ], - "additionalProperties": false - } - } -} \ No newline at end of file diff --git a/_includes/example2/instance.json b/_includes/example2/instance.json deleted file mode 100644 index acc5c4a8..00000000 --- a/_includes/example2/instance.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "/": { - "storage": { - "type": "disk", - "device": "/dev/sda1" - }, - "fstype": "btrfs", - "readonly": true - }, - "/var": { - "storage": { - "type": "disk", - "label": "8f3ba6f4-5c70-46ec-83af-0d5434953e5f" - }, - "fstype": "ext4", - "options": [ "nosuid" ] - }, - "/tmp": { - "storage": { - "type": "tmpfs", - "sizeInMB": 64 - } - }, - "/var/www": { - "storage": { - "type": "nfs", - "server": "my.nfs.server", - "remotePath": "/exports/mypath" - } - } -} \ No newline at end of file diff --git a/_includes/example2/schema1.json b/_includes/example2/schema1.json deleted file mode 100644 index 616f1ac7..00000000 --- a/_includes/example2/schema1.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "type": "object", - "properties": { - "/": {} - }, - "patternProperties": { - "^(/[^/]+)+$": {} - }, - "additionalProperties": false, - "required": [ "/" ] -} \ No newline at end of file diff --git a/_includes/example2/schema2.json b/_includes/example2/schema2.json deleted file mode 100644 index 167a7710..00000000 --- a/_includes/example2/schema2.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "type": "object", - "properties": { - "/": { "$ref": "http://some.site.somewhere/entry-schema#" } - }, - "patternProperties": { - "^(/[^/]+)+$": { "$ref": "http://some.site.somewhere/entry-schema#" } - }, - "additionalProperties": false, - "required": [ "/" ] -} \ No newline at end of file diff --git a/_includes/example2/storage_schema1.json b/_includes/example2/storage_schema1.json deleted file mode 100644 index 7bf92b14..00000000 --- a/_includes/example2/storage_schema1.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "properties": { - "type": { "enum": [ "disk" ] }, - "device": { - "type": "string", - "pattern": "^/dev/[^/]+(/[^/]+)*$" - } - }, - "required": [ "type", "device" ], - "additionalProperties": false -} \ No newline at end of file diff --git a/_includes/example2/storage_schema2.json b/_includes/example2/storage_schema2.json deleted file mode 100644 index 2c77835b..00000000 --- a/_includes/example2/storage_schema2.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "properties": { - "type": { "enum": [ "disk" ] }, - "label": { - "type": "string", - "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$" - } - }, - "required": [ "type", "label" ], - "additionalProperties": false -} \ No newline at end of file diff --git a/_includes/example2/storage_schema3.json b/_includes/example2/storage_schema3.json deleted file mode 100644 index 66aea6e1..00000000 --- a/_includes/example2/storage_schema3.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "properties": { - "type": { "enum": [ "nfs" ] }, - "remotePath": { - "type": "string", - "pattern": "^(/[^/]+)+$" - }, - "server": { - "type": "string", - "oneOf": [ - { "format": "hostname" }, - { "format": "ipv4" }, - { "format": "ipv6" } - ] - } - }, - "required": [ "type", "server", "remotePath" ], - "additionalProperties": false -} \ No newline at end of file diff --git a/_includes/example2/storage_schema4.json b/_includes/example2/storage_schema4.json deleted file mode 100644 index 7caa3cd6..00000000 --- a/_includes/example2/storage_schema4.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "properties": { - "type": { "enum": [ "tmpfs" ] }, - "sizeInMB": { - "type": "integer", - "minimum": 16, - "maximum": 512 - } - }, - "required": [ "type", "sizeInMB" ], - "additionalProperties": false -} \ No newline at end of file diff --git a/_includes/person.json b/_includes/person.json deleted file mode 100644 index 6e128524..00000000 --- a/_includes/person.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "title": "Person", - "type": "object", - "properties": { - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - }, - "age": { - "description": "Age in years", - "type": "integer", - "minimum": 0 - } - }, - "required": ["firstName", "lastName"] -} \ No newline at end of file diff --git a/example/address.json b/example/address.json index dd124d65..0967ef42 100644 --- a/example/address.json +++ b/example/address.json @@ -1,19 +1 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "An Address following the convention of http://microformats.org/wiki/hcard", - "type": "object", - "properties": { - "post-office-box": { "type": "string" }, - "extended-address": { "type": "string" }, - "street-address": { "type": "string" }, - "locality":{ "type": "string" }, - "region": { "type": "string" }, - "postal-code": { "type": "string" }, - "country-name": { "type": "string"} - }, - "required": ["locality", "region", "country-name"], - "dependencies": { - "post-office-box": ["street-address"], - "extended-address": ["street-address"] - } -} +{} diff --git a/example/calendar.json b/example/calendar.json index b716e8b5..0967ef42 100644 --- a/example/calendar.json +++ b/example/calendar.json @@ -1,38 +1 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "A representation of an event", - "type": "object", - "required": [ "dtstart", "summary" ], - "properties": { - "dtstart": { - "format": "date-time", - "type": "string", - "description": "Event starting time" - }, - "dtend": { - "format": "date-time", - "type": "string", - "description": "Event ending time" - }, - "summary": { "type": "string" }, - "location": { "type": "string" }, - "url": { "type": "string", "format": "uri" }, - "duration": { - "format": "time", - "type": "string", - "description": "Event duration" - }, - "rdate": { - "format": "date-time", - "type": "string", - "description": "Recurrence date" - }, - "rrule": { - "type": "string", - "description": "Recurrence rule" - }, - "category": { "type": "string" }, - "description": { "type": "string" }, - "geo": { "$ref": "http://json-schema.org/geo" } - } -} +{} diff --git a/example/card.json b/example/card.json index 59dbbc93..0967ef42 100644 --- a/example/card.json +++ b/example/card.json @@ -1,49 +1 @@ -{ - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "A representation of a person, company, organization, or place", - "type": "object", - "required": ["familyName", "givenName"], - "properties": { - "fn": { - "description": "Formatted Name", - "type": "string" - }, - "familyName": { "type": "string" }, - "givenName": { "type": "string" }, - "additionalName": { "type": "array", "items": { "type": "string" } }, - "honorificPrefix": { "type": "array", "items": { "type": "string" } }, - "honorificSuffix": { "type": "array", "items": { "type": "string" } }, - "nickname": { "type": "string" }, - "url": { "type": "string", "format": "uri" }, - "email": { - "type": "object", - "properties": { - "type": { "type": "string" }, - "value": { "type": "string", "format": "email" } - } - }, - "tel": { - "type": "object", - "properties": { - "type": { "type": "string" }, - "value": { "type": "string", "format": "phone" } - } - }, - "adr": { "$ref": "http://json-schema.org/address" }, - "geo": { "$ref": "http://json-schema.org/geo" }, - "tz": { "type": "string" }, - "photo": { "type": "string" }, - "logo": { "type": "string" }, - "sound": { "type": "string" }, - "bday": { "type": "string", "format": "date" }, - "title": { "type": "string" }, - "role": { "type": "string" }, - "org": { - "type": "object", - "properties": { - "organizationName": { "type": "string" }, - "organizationUnit": { "type": "string" } - } - } - } -} +{} diff --git a/example/geo.json b/example/geo.json index 4a0610ed..0967ef42 100644 --- a/example/geo.json +++ b/example/geo.json @@ -1,10 +1 @@ -{ - "id": "http://json-schema.org/geo", - "$schema": "http://json-schema.org/draft-06/schema#", - "description": "A geographical coordinate", - "type": "object", - "properties": { - "latitude": { "type": "number" }, - "longitude": { "type": "number" } - } -} \ No newline at end of file +{} diff --git a/example/index.md b/example/index.md new file mode 100644 index 00000000..0437e4d3 --- /dev/null +++ b/example/index.md @@ -0,0 +1 @@ +## Hello World diff --git a/example/person.json b/example/person.json new file mode 100644 index 00000000..0967ef42 --- /dev/null +++ b/example/person.json @@ -0,0 +1 @@ +{} diff --git a/example1.md b/example1.md deleted file mode 100644 index 026afc0c..00000000 --- a/example1.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -layout: page -title: Building a product schema ---- - -Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an *id*, a *name*, a *price*, and an optional set of *tags*. - -### Example JSON data for a product API - -An example product in this API is: - -```json -{% include example1/instance.json %} -``` - -While generally straightforward, that example leaves some open questions. For example, one may ask: - -- What is id? -- Is name required? -- Can price be 0? -- Are all tags strings? - -When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data. - -Starting the schema -------------------- - -To start a schema definition, let's begin with a basic JSON schema: - -```json -{% include example1/schema1.json %} -``` - -The above schema has four properties called *keywords*. The *title* and *description* keywords are descriptive only, in that they do not add constraints to the data being validated. The intent of the schema is stated with these two keywords (that is, this schema describes a product). - -The *type* keyword defines the first constraint on our JSON data: it has to be a JSON Object. - -Finally, the *$schema* keyword states that this schema is written according to the draft-06 specification. - -Defining the properties ------------------------ - -Next let's answer our previous questions about this API, starting with id. - -### What is id? - -*id* is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required. - -In JSON Schema terms, we can update our schema to: - -```json -{% include example1/schema2.json %} -``` - -### Is name required? - -*name* is a string value that describes a product. Since there isn't much to a product without a name, it also is required. Adding this gives us the schema: - -```json -{% include example1/schema3.json %} -``` - -### Can price be 0? - -According to Acme's docs, there are no free products. So we need to specify *exclusiveMinimum*. If we wanted to include 0 as a valid price, we would have specified *minimum* instead. Therefore, we can update our schema with *price*: - -```json -{% include example1/schema4.json %} -``` - -### Are all tags strings? - -Finally, we come to the *tags* property. Unlike the previous properties, tags have many values, and is represented as a JSON array. If, according to Acme's docs, all tags must be strings, but you aren't required to specify tags; we would simply leave *tags* out of the list of required properties. - -However, Acme's docs add two constraints: - -- there must be at least one tag, -- all tags must be unique. - -The first constraint can be added with *minItems*, and the second one by specifying *uniqueItems* as being true: - -```json -{% include example1/schema5.json %} -``` - -Summary -------- - -The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the [full standard draft](#definitions). - -As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a *dimensions* property for the size of the product, and the second is a *warehouseLocation* field for where the warehouse that stores them is geographically located. - -And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the [canonical one](http://json-schema.org/geo). - -### Set of products: - -```json -{% include example1/set_instance.json %} -``` - -### Set of products schema: - -```json -{% include example1/set_schema.json %} -``` diff --git a/example2.md b/example2.md deleted file mode 100644 index af537a5e..00000000 --- a/example2.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -layout: page -title: Building a mount point schema ---- - -This example shows a possible JSON representation of a hypothetical machine's mount points as represented in an `/etc/fstab` file. - -An entry in an fstab file can have many different forms. Here is a possible representation of a full fstab: - -```json -{% include example2/instance.json %} -``` - -Not all constraints to an fstab file can be modeled using JSON Schema alone; however, it can represent a good number of them. We will add constraints one after the other until we get to a satisfactory result. - -Base schema ------------ - -We will start with a base schema expressing the following constraints: - -- the list of entries is a JSON object; -- the member names (or property names) of this object must all be valid, absolute paths; -- there must be an entry for the root filesystem (ie, `/`). - -We also want the schema to be regarded as a draft v6 schema, we must therefore specify *$schema*: - -```json -{% include example2/schema1.json %} -``` - -Note how the valid paths constraint is enforced here: - -- we have a *properties* keyword with only a `/` entry; -- we use *patternProperties* to match other property names via a regular expression (note that it does not match `/`); -- as *additionalProperties* is false, it constrains object properties to be either `/` or to match the regular expression. - -You will notice that the regular expression is explicitly anchored (with `^` and `$`): in JSON Schema, regular expressions (in *patternProperties* and in *pattern*) are not anchored by default. - -For now, the schemas describing individual entries are empty: we will start describing the constraints in the following paragraphs, using another schema, which we will reference from the main schema when we are ready. - -The entry schema - starting out -------------------------------- - -Here again we will proceed step by step. We will start with the global structure of our schema, which will be as such: - -```json -{% include example2/entry_schema1.json %} -``` - -You should already be familiar with some of the constraints: - -- an fstab entry must be an object (`"type": "object"`); -- it must have one property with name *storage* (`"required": [ "storage" ]`); -- the *storage* property must also be an object. - -There are a couple of novelties: - -- you will notice the appearance of JSON References, via the *$ref* keyword; here, all references used are local to the schema, and the fragment part is a URI encoded JSON Pointer; -- you will notice the appearance of an *id*: this is the URI of this resource; we assume here that this URI is the actual URI of this schema; -- the *oneOf* keyword is new in draft v4; its value is an array of schemas, and an instance is valid if and only if it is valid against exactly one of these schemas; -- finally, the *definitions* keyword is a standardized placeholder in which you can define inline subschemas to be used in a schema. - -### The *fstype*, *options* and *readonly* properties - -The entry schema - adding constraints -------------------------------------- - -Let's now extend this skeleton to add constraints to these three properties. Note that none of them are required: - -- we will pretend that we only support `ext3`, `ext4` and `btrfs` as filesystem types; -- *options* must be an array, and the items in this array must be strings; moreover, there must be at least one item, and all items should be unique; -- *readonly* must be a boolean. - -With these added constraints, the schema now looks like this: - -```json -{% include example2/entry_schema2.json %} -``` - -For now, all definitions are empty (an empty JSON Schema validates all instances). We will write schemas for individual definitions below, and fill these schemas into the entry schema. - -The *diskDevice* storage type ------------------------------ - -This storage type has two required properties, *type* and *device*. The type can only be *disk*, and the device must be an absolute path starting with */dev*. No other properties are allowed: - -```json -{% include example2/storage_schema1.json %} -``` - -You will have noted that we need not specify that *type* must be a string: the constraint described by *enum* is enough. - -The *diskUUID* storage type ---------------------------- - -This storage type has two required properties, *type* and *label*. The type can only be *disk*, and the label must be a valid UUID. No other properties are allowed: - -```json -{% include example2/storage_schema2.json %} -``` - -The *nfs* storage type ----------------------- - -This storage type has three required properties: *type*, *server* and *remotePath*. What is more, the server may be either a host name, an IPv4 address or an IPv6 address. - -For the constraints on *server*, we use a new keyword: *format*. While it is not required that *format* be supported, we will suppose that it is here: - -```json -{% include example2/storage_schema3.json %} -``` - -The *tmpfs* storage type ------------------------- - -This storage type has two required properties: *type* and *sizeInMB*. The size can only be an integer. What is more, we will require that the size be between 16 and 512, inclusive: - -```json -{% include example2/storage_schema4.json %} -``` - -The full entry schema ---------------------- - -The resulting schema is quite large: - -```json -{% include example2/entry_schema3.json %} -``` - -Plugging this into our main schema ----------------------------------- - -Now that all possible entries have been described, we can refer to the entry schema from our main schema. We will, again, use a JSON Reference here: - -```json -{% include example2/schema2.json %} -``` - -Wrapping up ------------ - -This example is much more advanced than the previous example; you will have learned of schema referencing and identification, you will have been introduced to other keywords. There are also a few additional points to consider. - -### The schema can be improved - -This is only an example for learning purposes. Some additional constraints could be described. For instance: - -- it makes no sense for `/` to be mounted on a tmpfs filesystem; -- it makes no sense to specify the filesystem type if the storage is either NFS or tmpfs. - -As an exercise, you can always try to add these constraints. It would probably require splitting the schema further. - -### Not all constraints can be expressed - -JSON Schema limits itself to describing the structure of JSON data, it cannot express functional constraints. - -If we take an NFS entry as an example, JSON Schema alone cannot check that the submitted NFS server's hostname, or IP address, is actually correct: this check is left to applications. - -### Tools have varying JSON Schema support - -While this is not a concern if you know that the schema you write will be used by you alone, you should keep this in mind if you write a schema which other people can potentially use. The schema we have written here has some features which can be problematic for portability: - -- *format* support is optional, and as such other tools may ignore this keyword: this can lead to a different validation outcome for the same data; -- it uses regular expressions: care should be taken not to use any advanced features (such as lookarounds), since they may not be supported at the other end; -- it uses *$schema* to express the need to use draft v6 compliant processing, but not all tools support draft v6. diff --git a/examples.md b/examples.md deleted file mode 100644 index 7e892480..00000000 --- a/examples.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: page -title: Examples ---- - -Here is a basic example of a JSON Schema: - -```json -{% include person.json%} -``` - -Example schemas ---------------- - -These sample schemas describe simple data structures which can be expressed as JSON. The "canonical url" links omit the ".json" extension, which is the correct -way to reference the schema in a ``$ref``, but is not friendly to web browsers. -The larger links use ".json" for browser compatibility. - -|------------------------------------------------------------------------------|-----------------------------------------------------------------| -| [Geographic Coordinate](example/geo.json)
[(canonical url)](geo) | a location as longitude and latitude | -| [Card](example/card.json)
[(canonical url)](card) | a microformat-style representation of a person, company, organization, or place | -| [Calendar](example/calendar.json)
[(canonical url)](calendar) | a microformat-style representation of an event | -| [Address](example/address.json)
[(canonical url)](address) | a microformat-style representation of a street address | - -Walkthroughs ------------- - -The two examples below are step-by-step guides into building a schema: - -- [a simple example](example1.md) which covers a classical product catalog description. -- [a more advanced example](example2.md), using JSON Schema to describe filesystem entries in a Unix-like /etc/fstab file. - -The [Space Telescope Science Institute](http://www.stsci.edu/) has also published a [guide aimed at schema authors](http://spacetelescope.github.io/understanding-json-schema/). diff --git a/index.md b/index.md index 2d480d20..bdc2ade0 100644 --- a/index.md +++ b/index.md @@ -10,60 +10,48 @@ permalink: / **JSON Schema** is a vocabulary that allows you to **annotate** and **validate** JSON documents. -Advantages ----------- +## Advantages
### JSON Schema -- describes your existing data format -- clear, human- and machine-readable documentation -- complete structural validation, useful for - - automated testing - - validating client-submitted data +* Describes your existing data format(s). +* Provides clear human- and machine- readable documentation. +* Validates data which is useful for: + * Automated testing. + * Ensuring quality of client submitted data. +
### JSON Hyper-Schema -- make any JSON format a hypermedia format - no constraints on document structure -- use [URI Templates](https://tools.ietf.org/html/rfc6570) with instance data -- describe client data for use with links using JSON Schema -- recognize collections and collection items +* Make any JSON format a hypermedia format with no constraints on document structure +* Allows use of [URI Templates](https://tools.ietf.org/html/rfc6570) with instance data +* Describe client data for use with links using JSON Schema. +* Recognizes collections and collection items.
-Project Status --------------- +## Project Status -The JSON Schema project intends to shepherd the Core, Validation, and Hyper-Schema specifications -to RFC status. Currently, we are continuing to improve our self-published Internet-Drafts. -The next step will be to get the drafts adopted by an IETF Working Group. +The JSON Schema project intends to shepherd the Core, Validation, and Hyper-Schema specifications to RFC status. Currently, we are continuing to improve our self-published Internet-Drafts. The next step will be to get the drafts adopted by an IETF Working Group. In the meantime, publication of Internet-Draft documents can be tracked through the IETF: -- [JSON Schema (core)](https://datatracker.ietf.org/doc/draft-handrews-json-schema/) -- [JSON Schema Validation](https://datatracker.ietf.org/doc/draft-handrews-json-schema-validation/) -- [JSON Hyper-Schema](https://datatracker.ietf.org/doc/draft-handrews-json-schema-hyperschema/) -- [Relative JSON Pointers](https://datatracker.ietf.org/doc/draft-handrews-relative-json-pointer/) - -Internet-Drafts expire after six months, so our goal is to publish often enough to always have -a set of unexpired drafts available. There may be brief gaps as we wrap up each draft and finalize -the text. +* [JSON Schema (core)](https://datatracker.ietf.org/doc/draft-handrews-json-schema/) +* [JSON Schema Validation](https://datatracker.ietf.org/doc/draft-handrews-json-schema-validation/) +* [JSON Hyper-Schema](https://datatracker.ietf.org/doc/draft-handrews-json-schema-hyperschema/) +* [Relative JSON Pointers](https://datatracker.ietf.org/doc/draft-handrews-relative-json-pointer/) -The intention, particularly for vocabularies such as validation which have been widely -implemented, is to remain as compatible as possible from draft to draft. However, these are still -drafts, and given a clear enough need validated with the user community, major changes can occur. +Internet-Drafts expire after six months, so our goal is to publish often enough to always have a set of unexpired drafts available. There may be brief gaps as we wrap up each draft and finalize the text. -Progress on the next set of Internet-Drafts can be tracked on GitHub. -The [draft-08](https://github.com/json-schema-org/json-schema-spec/milestone/6) milestone -will track the evolving scope of the draft +The intention, particularly for vocabularies such as validation which have been widely implemented, is to remain as compatible as possible from draft to draft. However, these are still drafts, and given a clear enough need validated with the user community, major changes can occur. -
+Progress on the next set of Internet-Drafts can be tracked on GitHub. The [draft-08](https://github.com/json-schema-org/json-schema-spec/milestone/6) milestone will track the evolving scope of the draft -Quickstart ----------- +## Quickstart The JSON document being validated or described we call the *instance*, and the document containing the description is called the *schema*. @@ -76,25 +64,23 @@ The most basic schema is a blank JSON object, which constrains nothing, allows a You can apply constraints on an instance by adding validation keywords to the schema. For example, the "type" keyword can be used to restrict an instance to an object, array, string, number, boolean, or null: ```json -{"type": "string"} +{ "type": "string" } ``` JSON Schema is hypermedia ready, and ideal for annotating your existing JSON-based HTTP API. JSON Schema documents are identified by URIs, which can be used in HTTP Link headers, and inside JSON Schema documents to allow recursive definitions. -More ----- +## More Interested? Check out: -- the [specification](specification.html) -- some [examples](examples.md) -- the growing list of [JSON (Hyper-)Schema software](implementations.html) +* The [specification](./specification.md) +* [Learning resources](./learn/index.md) +* the growing list of [JSON (Hyper-)Schema software](./implementations.md) -We encourage updating to the latest specification, as described by the draft-07 meta-schemas. However, if you are still using draft-04, you may be interested in: -- this [excellent guide](http://spacetelescope.github.io/understanding-json-schema/) for schema authors, from the [Space Telescope Science Institute](http://www.stsci.edu/) +We encourage updating to the latest specification, as described by the draft-07 meta-schemas. Questions? Feeling helpful? Get involved on: -- the [GitHub repo](http://github.com/json-schema-org/json-schema-spec) -- the [Google Group](https://groups.google.com/forum/#!forum/json-schema) -- the [Slack channel](https://join.slack.com/t/json-schema/shared_invite/enQtMjk1NDcyNDI2NTAwLTcyYmYwMjdmMmUxNzZjYzIxNGU2YjdkNzdlOGZiNjIwNDI2M2Y3NmRkYjA4YmMwODMwYjgyOTFlNWZjZjAyNjg) +* [GitHub](http://github.com/json-schema-org/json-schema-spec) +* [Google Groups](https://groups.google.com/forum/#!forum/json-schema) +* [Slack](https://join.slack.com/t/json-schema/shared_invite/enQtMjk1NDcyNDI2NTAwLTcyYmYwMjdmMmUxNzZjYzIxNGU2YjdkNzdlOGZiNjIwNDI2M2Y3NmRkYjA4YmMwODMwYjgyOTFlNWZjZjAyNjg) diff --git a/learn/examples/address.schema.json b/learn/examples/address.schema.json new file mode 100644 index 00000000..77fadaf2 --- /dev/null +++ b/learn/examples/address.schema.json @@ -0,0 +1,34 @@ +{ + "$id": "https://example.com/address.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "An address similar to http://microformats.org/wiki/h-card", + "type": "object", + "properties": { + "post-office-box": { + "type": "string" + }, + "extended-address": { + "type": "string" + }, + "street-address": { + "type": "string" + }, + "locality": { + "type": "string" + }, + "region": { + "type": "string" + }, + "postal-code": { + "type": "string" + }, + "country-name": { + "type": "string" + } + }, + "required": [ "locality", "region", "country-name" ], + "dependencies": { + "post-office-box": [ "street-address" ], + "extended-address": [ "street-address" ] + } +} diff --git a/learn/examples/calendar.schema.json b/learn/examples/calendar.schema.json new file mode 100644 index 00000000..bb98ca30 --- /dev/null +++ b/learn/examples/calendar.schema.json @@ -0,0 +1,47 @@ +{ + "$id": "https://example.com/address.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "A representation of an event", + "type": "object", + "required": [ "dtstart", "summary" ], + "properties": { + "dtstart": { + "type": "string", + "description": "Event starting time" + }, + "dtend": { + "type": "string", + "description": "Event ending time" + }, + "summary": { + "type": "string" + }, + "location": { + "type": "string" + }, + "url": { + "type": "string" + }, + "duration": { + "type": "string", + "description": "Event duration" + }, + "rdate": { + "type": "string", + "description": "Recurrence date" + }, + "rrule": { + "type": "string", + "description": "Recurrence rule" + }, + "category": { + "type": "string" + }, + "description": { + "type": "string" + }, + "geo": { + "$ref": "http://example.com/geo.schema.json" + } + } +} diff --git a/learn/examples/card.schema.json b/learn/examples/card.schema.json new file mode 100644 index 00000000..7740a8b9 --- /dev/null +++ b/learn/examples/card.schema.json @@ -0,0 +1,99 @@ +{ + "$id": "https://example.com/address.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "A representation of a person, company, organization, or place", + "type": "object", + "required": [ "familyName", "givenName" ], + "properties": { + "fn": { + "description": "Formatted Name", + "type": "string" + }, + "familyName": { + "type": "string" + }, + "givenName": { + "type": "string" + }, + "additionalName": { + "type": "array", + "items": { + "type": "string" + } + }, + "honorificPrefix": { + "type": "array", + "items": { + "type": "string" + } + }, + "honorificSuffix": { + "type": "array", + "items": { + "type": "string" + } + }, + "nickname": { + "type": "string" + }, + "url": { + "type": "string" + }, + "email": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "value": { + "type": "string" + } + } + }, + "tel": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "value": { + "type": "string" + } + } + }, + "adr": { "$ref": "http://example.com/address.schema.json" }, + "geo": { "$ref": "http://example.com/geographical-location.schema.json" }, + "tz": { + "type": "string" + }, + "photo": { + "type": "string" + }, + "logo": { + "type": "string" + }, + "sound": { + "type": "string" + }, + "bday": { + "type": "string" + }, + "title": { + "type": "string" + }, + "role": { + "type": "string" + }, + "org": { + "type": "object", + "properties": { + "organizationName": { + "type": "string" + }, + "organizationUnit": { + "type": "string" + } + } + } + } +} diff --git a/learn/examples/geographical-location.schema.json b/learn/examples/geographical-location.schema.json new file mode 100644 index 00000000..86656397 --- /dev/null +++ b/learn/examples/geographical-location.schema.json @@ -0,0 +1,20 @@ +{ + "id": "https://example.com/geographical-location.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Longitude and Latitude Values", + "description": "A geographical coordinate.", + "required": [ "latitude", "longitude" ], + "type": "object", + "properties": { + "latitude": { + "type": "number", + "minimum": -90, + "maximum": 90 + }, + "longitude": { + "type": "number", + "minimum": -180, + "maximum": 180 + } + } +} diff --git a/learn/file-system.md b/learn/file-system.md new file mode 100644 index 00000000..24b77fda --- /dev/null +++ b/learn/file-system.md @@ -0,0 +1,420 @@ +--- +layout: page +title: Modeling a file system with JSON Schema +--- + +* [Introduction](#introduction) +* [Creating the `fstab` schema](#fstab-schema) +* [Starting the `entry` schema](#entry-schema) +* [Constraining an entry](#constraining-entry) +* [The `diskDevice` definition](#diskdevice) +* [The `diskUUID` definition](#diskuuid) +* [The `nfs` definition](#nfs) +* [The `tmpfs` definition](#tmpfs) +* [The full entry schema](#full-entry) +* [Referencing the `entry` schema in the `fstab` schema](#referencing-entry) + +## Introduction + +> Not all constraints to an fstab file can be modeled using JSON Schema alone; however, it can represent a good number of them and the exercise is useful to demonstrate how constraints work. The examples provided are illustrative of the JSON Schema concepts rather than a real, working schema for an fstab file. + +This example shows a possible JSON Schema representation of file system mount points as represented in an [`/etc/fstab`](https://en.wikipedia.org/wiki/Fstab) file. + +An entry in an fstab file can have many different forms; Here is an example: + +```json +{ + "/": { + "storage": { + "type": "disk", + "device": "/dev/sda1" + }, + "fstype": "btrfs", + "readonly": true + }, + "/var": { + "storage": { + "type": "disk", + "label": "8f3ba6f4-5c70-46ec-83af-0d5434953e5f" + }, + "fstype": "ext4", + "options": [ "nosuid" ] + }, + "/tmp": { + "storage": { + "type": "tmpfs", + "sizeInMB": 64 + } + }, + "/var/www": { + "storage": { + "type": "nfs", + "server": "my.nfs.server", + "remotePath": "/exports/mypath" + } + } +} +``` + +## Creating the `fstab` schema + +We will start with a base JSON Schema expressing the following constraints: + +* the list of entries is a JSON object; +* the member names (or property names) of this object must all be valid, absolute paths; +* there must be an entry for the root filesystem (ie, `/`). + +Building out our JSON Schema from top to bottom: + +* The [`$id`](http://json-schema.org/latest/json-schema-core.html#rfc.section.8.2) keyword. +* The [`$schema`](http://json-schema.org/latest/json-schema-core.html#rfc.section.7) keyword. +* The [`type`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.1) validation keyword. +* The [`required`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.3) validation keyword. +* The [`properties`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.4) validation keyword. + * The `/` key is empty now; We will fill it out later. +* The [`patternProperties`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.5) validation keyword. + * This matches other property names via a regular expression. Note: it does not match `/`. + * The `^(/[^/]+)+$` key is empty now; We will fill it out later. +* The [`additionalProperties`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.6) validation keyword. + * The value here is `false` to constrain object properties to be either `/` or to match the regular expression. + +> You will notice that the regular expression is explicitly anchored (with `^` and `$`): in JSON Schema, regular expressions (in `patternProperties` and in `pattern`) are not anchored by default. + +```json +{ + "$id": "http://example.com/fstab", + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "/" ], + "properties": { + "/": {} + }, + "patternProperties": { + "^(/[^/]+)+$": {} + }, + "additionalProperties": false, +} +``` + +## Starting the `entry` schema + +We will start with an outline of the JSON schema which adds new concepts to what we've already demonstrated. + +We saw these keywords in the prior exercise: `$id`, `$schema`, `type`, `required` and `properties`. + +To this we add: + +* The [`description`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) annotation keyword. +* The [`oneOf`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.7.3) keyword. +* The [`$ref`](http://json-schema.org/latest/json-schema-core.html#rfc.section.8.3) keyword. + * In this case, all references used are local to the schema using a relative fragment URI (`#/...`). +* The [`definitions`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.9) keyword. + * Including several key names which we will define later. + +```json +{ + "$id": "http://example.com/entry-schema", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "JSON Schema for an fstab entry", + "type": "object", + "required": [ "storage" ], + "properties": { + "storage": { + "type": "object", + "oneOf": [ + { "$ref": "#/definitions/diskDevice" }, + { "$ref": "#/definitions/diskUUID" }, + { "$ref": "#/definitions/nfs" }, + { "$ref": "#/definitions/tmpfs" } + ] + } + }, + "definitions": { + "diskDevice": {}, + "diskUUID": {}, + "nfs": {}, + "tmpfs": {} + } +} +``` + +## Constraining an entry + +Let's now extend this skeleton to add constraints to some of the properties. + +* Our `fstype` key uses the [`enum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.2) validation keyword. +* Our `options` key uses the following: + * The `type` validation keyword (see above). + * The [`minItems`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.4) validation keyword. + * The [`items`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.1) validation keyword. + * The [`uniqueItems`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.5) validation keyword. + * Together these say: `options` must be an array, and the items therein must be strings, there must be at least one item, and all items should be unique. +* We have a `readonly` key. + +With these added constraints, the schema now looks like this: + +```json +{ + "$id": "http://example.com/entry-schema", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "JSON Schema for an fstab entry", + "type": "object", + "required": [ "storage" ], + "properties": { + "storage": { + "type": "object", + "oneOf": [ + { "$ref": "#/definitions/diskDevice" }, + { "$ref": "#/definitions/diskUUID" }, + { "$ref": "#/definitions/nfs" }, + { "$ref": "#/definitions/tmpfs" } + ] + }, + "fstype": { + "enum": [ "ext3", "ext4", "btrfs" ] + }, + "options": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "readonly": { + "type": "boolean" + } + }, + "definitions": { + "diskDevice": {}, + "diskUUID": {}, + "nfs": {}, + "tmpfs": {} + } +} +``` + +## The `diskDevice` definition + +One new keyword is introduced here: + +* The [`pattern`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.3.3) validation keyword notes the `device` key must be an absolute path starting with */dev*. + +```json +{ + "diskDevice": { + "properties": { + "type": { + "enum": [ "disk" ] + }, + "device": { + "type": "string", + "pattern": "^/dev/[^/]+(/[^/]+)*$" + } + }, + "required": [ "type", "device" ], + "additionalProperties": false + } +} +``` + +## The `diskUUID` definition + +No new keywords are introduced here. + +We do have a new key: `label` and the `pattern` validation keyword states it must be a valid UUID. + +```json +{ + "diskUUID": { + "properties": { + "type": { + "enum": [ "disk" ] + }, + "label": { + "type": "string", + "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$" + } + }, + "required": [ "type", "label" ], + "additionalProperties": false + } +} +``` + +## The `nfs` definition + +We find another new keyword: + +* The [`format`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.7) annotation and assertion keyword. + +```json +{ + "nfs": { + "properties": { + "type": { "enum": [ "nfs" ] }, + "remotePath": { + "type": "string", + "pattern": "^(/[^/]+)+$" + }, + "server": { + "type": "string", + "oneOf": [ + { "format": "hostname" }, + { "format": "ipv4" }, + { "format": "ipv6" } + ] + } + }, + "required": [ "type", "server", "remotePath" ], + "additionalProperties": false + } +} +``` + +## The `tmpfs` definition + +Our last definition introduces two new keywords: + +* The [`minimum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.4) validation keyword. +* The [`maximum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.2) validation keword. +* Together these require the size be between 16 and 512, inclusive. + +```json +{ + "tmpfs": { + "properties": { + "type": { "enum": [ "tmpfs" ] }, + "sizeInMB": { + "type": "integer", + "minimum": 16, + "maximum": 512 + } + }, + "required": [ "type", "sizeInMB" ], + "additionalProperties": false + } +} +``` + +## The full entry schema + +The resulting schema is quite large: + +```json +{ + "$id": "http://example.com/entry-schema", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "JSON Schema for an fstab entry", + "type": "object", + "required": [ "storage" ], + "properties": { + "storage": { + "type": "object", + "oneOf": [ + { "$ref": "#/definitions/diskDevice" }, + { "$ref": "#/definitions/diskUUID" }, + { "$ref": "#/definitions/nfs" }, + { "$ref": "#/definitions/tmpfs" } + ] + }, + "fstype": { + "enum": [ "ext3", "ext4", "btrfs" ] + }, + "options": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "readonly": { + "type": "boolean" + } + }, + "definitions": { + "diskDevice": { + "properties": { + "type": { + "enum": [ "disk" ] + }, + "device": { + "type": "string", + "pattern": "^/dev/[^/]+(/[^/]+)*$" + } + }, + "required": [ "type", "device" ], + "additionalProperties": false + } + }, + "diskUUID": { + "properties": { + "type": { + "enum": [ "disk" ] + }, + "label": { + "type": "string", + "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$" + } + }, + "required": [ "type", "label" ], + "additionalProperties": false + }, + "nfs": { + "properties": { + "type": { "enum": [ "nfs" ] }, + "remotePath": { + "type": "string", + "pattern": "^(/[^/]+)+$" + }, + "server": { + "type": "string", + "oneOf": [ + { "format": "hostname" }, + { "format": "ipv4" }, + { "format": "ipv6" } + ] + } + }, + "required": [ "type", "server", "remotePath" ], + "additionalProperties": false + }, + "tmpfs": { + "properties": { + "type": { "enum": [ "tmpfs" ] }, + "sizeInMB": { + "type": "integer", + "minimum": 16, + "maximum": 512 + } + }, + "required": [ "type", "sizeInMB" ], + "additionalProperties": false + } +} +} +``` + +## Referencing the `entry` schema in the `fstab` schema + +Coming full circle we use the `$ref` keyword to add our entry schema into the keys left empty at the start of the exercise: + +* The `/` key. +* The `^(/[^/]+)+$` key. + +```json +{ + "$id": "http://example.com/fstab", + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "/" ], + "properties": { + "/": { "$ref": "http://example.com/entry-schema" } + }, + "patternProperties": { + "^(/[^/]+)+$": { "$ref": "http://example.com/entry-schema" } + }, + "additionalProperties": false, +} +``` diff --git a/learn/getting-started-step-by-step.md b/learn/getting-started-step-by-step.md new file mode 100644 index 00000000..4ff5ce2d --- /dev/null +++ b/learn/getting-started-step-by-step.md @@ -0,0 +1,382 @@ +--- +layout: page +title: Getting Started Step-By-Step +--- + +* [Introduction](#intro) +* [Starting the schema](#starting) +* [Defining the properties](#properties) +* [Going deeper with properties](#properties-deeper) +* [Nesting data structures](#nesting) +* [References outside the schema](#references) +* [Taking a look at data for our defined JSON Schema](#data) + +## Introduction + +The following example is by no means definitive of all the value JSON Schema can provide. For this you will need to go deep into the specification itself -- learn more at [http://json-schema.org/specification.html](http://json-schema.org/specification.html). + +Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has: + +* An identifier: `productId` +* A product name: `productName` +* A selling cost for the consumer: `price` +* An optional set of tags: `tags`. + +For example: + +```json +{ + "productId": 1, + "productName": "A green door", + "price": 12.50, + "tags": [ "home", "green" ] +} +``` + +While generally straightforward, the example leaves some open questions. Here are just a few of them: + +* What is `productId`? +* Is `productName` required? +* Can the `price` be zero (0)? +* Are all of the `tags` string values? + +When you're talking about a data format, you want to have metadata about what keys mean, including the valid inputs for those keys. **JSON Schema** is a proposed IETF standard how to answer those questions for data. + +## Starting the schema + +To start a schema definition, let's begin with a basic JSON schema. + +We start with four properties called **keywords** which are expressed as [JSON](https://www.json.org/) keys. + +> Yes. the standard uses a JSON data document to describe data documents, most often that are also JSON data documents but could be in any number of other content types like `text/xml`. + +* The [`$schema`](http://json-schema.org/latest/json-schema-core.html#rfc.section.7) keyword states that this schema is written according to the a specific draft of the standard and used for a variety of reasons, primarily version control. +* The [`$id`](http://json-schema.org/latest/json-schema-core.html#rfc.section.8.2) keyword defines a URI for the schema, and the base URI that other URI references within the schema are resolved against. +* The [`title`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) and [`description`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) annotation keywords are descriptive only. They do not add constraints to the data being validated. The intent of the schema is stated with these two keywords. +* The [`type`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.1) validation keyword defines the first constraint on our JSON data and in this case it has to be a JSON Object. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product in the catalog", + "type": "object" +} +``` + +We introduce the following pieces of terminology when we start the schema: + +* [Schema Keyword](http://json-schema.org/latest/json-schema-core.html#rfc.section.4.3.1): `$schema` and `$id`. +* [Schema Annotations](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10): `title` and `description`. +* [Validation Keyword](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6): `type`. + +## Defining the properties + +`productId` is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required. + +In JSON Schema terms, we update our schema to add: + +* The [`properties`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.4) validation keyword. +* The `productId` key. + * `description` schema annotation and `type` validation keyword is noted -- we covered both of these in the previous section. +* The [`required`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.3) validation keyword listing `productId`. + + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product from Acme's catalog", + "type": "object", + "properties": { + "productId": { + "description": "The unique identifier for a product", + "type": "integer" + } + }, + "required": [ "productId" ] +} +``` + +* `productName` is a string value that describes a product. Since there isn't much to a product without a name it also is required. +* Since the `required` validation keyword is an array of strings we can note multiple keys as required; We now include `productName`. +* There isn't really any difference between `productId` and `productName` -- we include both for completeness since computers typically pay attention to identifiers and humans typically pay attention to names. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product from Acme's catalog", + "type": "object", + "properties": { + "productId": { + "description": "The unique identifier for a product", + "type": "integer" + }, + "productName": { + "description": "Name of the product", + "type": "string" + } + }, + "required": [ "productId", "productName" ] +} +``` + +## Going deeper with properties + +According to the store owner there are no free products. ;) + +* The `price` key is added with the usual `description` schema annotation and `type` validation keywords covered previously. It is also included in the array of keys defined by the `required` validation keyword. +* We specify the value of `price` must be something other than zero using the [`exclusiveMinimum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.5) validation keyword. + * If we wanted to include zero as a valid price we would have specified the [`minimum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.4) validation keyword. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product from Acme's catalog", + "type": "object", + "properties": { + "productId": { + "description": "The unique identifier for a product", + "type": "integer" + }, + "productName": { + "description": "Name of the product", + "type": "string" + }, + "price": { + "description": "The price of the product", + "type": "number", + "exclusiveMinimum": 0 + } + }, + "required": [ "productId", "productName", "price" ] +} +``` + +Next, we come to the `tags` key. + +The store owner has said this: + +* If there are tags there must be at least one tag, +* All tags must be unique; no duplication within a single product. +* All tags must be text. +* Tags are nice but they aren't required to be present. + +Therefore: + +* The `tags` key is added with the usual annotations and keywords. +* This time the `type` validation keyword is `array`. +* We introduce the [`items`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.1) validation keyword so we can define what appears in the array. In this case: `string` values via the `type` validation keyword. +* The [`minItems`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.4) validation keyword is used to make sure there is at least one item in the array. +* The [`uniqueItems`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.5) validation keyword notes all of the items in the array must be unique relative to one another. +* We did not add this key to the `required` validation keyword array because it is optional. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product from Acme's catalog", + "type": "object", + "properties": { + "productId": { + "description": "The unique identifier for a product", + "type": "integer" + }, + "productName": { + "description": "Name of the product", + "type": "string" + }, + "price": { + "description": "The price of the product", + "type": "number", + "exclusiveMinimum": 0 + }, + "tags": { + "description": "Tags for the product", + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "uniqueItems": true + } + }, + "required": [ "productId", "productName", "price" ] +} +``` + +## Nesting data structures + +Up until this point we've been dealing with a very flat schema -- only one level. This section demonstrates nested data structures. + +* The `dimensions` key is added using the concepts we've previously discovered. Since the `type` validation keyword is `object` we can use the `properties` validation keyword to define a nested data structure. + * We omitted the `description` annotation keyword for brevity in the example. While it's usually preferable to annotate thoroughly in this case the structure and key names are fairly familiar to most developers. +* You will note the scope of the `required` validation keyword is applicable to the dimensions key and not beyond. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product from Acme's catalog", + "type": "object", + "properties": { + "productId": { + "description": "The unique identifier for a product", + "type": "integer" + }, + "productName": { + "description": "Name of the product", + "type": "string" + }, + "price": { + "description": "The price of the product", + "type": "number", + "exclusiveMinimum": 0 + }, + "tags": { + "description": "Tags for the product", + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "uniqueItems": true + }, + "dimensions": { + "type": "object", + "properties": { + "length": { + "type": "number" + }, + "width": { + "type": "number" + }, + "height": { + "type": "number" + } + }, + "required": [ "length", "width", "height" ] + } + }, + "required": [ "productId", "productName", "price" ] +} +``` + +## References outside the schema + +So far our JSON schema has been wholly self contained. It is very common to share JSON schema across many data structures for reuse, readability and maintainability among other reasons. + +For this example we introduce a new JSON Schema resource and for both properties therein: +* We use the `minimum` validation keyword noted earlier. +* We add the http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.2 validation keyword. +* Combined, these give us a range to use in validation. + +```json +{ + "id": "https://example.com/geographical-location.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Longitude and Latitude", + "description": "A geographical coordinate on a planet (most commonly Earth).", + "required": [ "latitude", "longitude" ], + "type": "object", + "properties": { + "latitude": { + "type": "number", + "minimum": -90, + "maximum": 90 + }, + "longitude": { + "type": "number", + "minimum": -180, + "maximum": 180 + } + } +} +``` + +Next we add a reference to this new schema so it can be incorporated. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://example.com/product.schema.json", + "title": "Product", + "description": "A product from Acme's catalog", + "type": "object", + "properties": { + "productId": { + "description": "The unique identifier for a product", + "type": "integer" + }, + "productName": { + "description": "Name of the product", + "type": "string" + }, + "price": { + "description": "The price of the product", + "type": "number", + "exclusiveMinimum": 0 + }, + "tags": { + "description": "Tags for the product", + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "uniqueItems": true + }, + "dimensions": { + "type": "object", + "properties": { + "length": { + "type": "number" + }, + "width": { + "type": "number" + }, + "height": { + "type": "number" + } + }, + "required": [ "length", "width", "height" ] + }, + "warehouseLocation": { + "description": "Coordinates of the warehouse where the product is located.", + "$ref": "https://example.com/geographical-location.schema.json" + } + }, + "required": [ "productId", "productName", "price" ] +} +``` + +## Taking a look at data for our defined JSON Schema + +We've certainly expanded on the concept of a product since our earliest sample data (scroll up to the top). Let's take a look at data which matches the JSON Schema we have defined. + +```json + + { + "productId": 1, + "productName": "An ice sculpture", + "price": 12.50, + "tags": [ "cold", "ice" ], + "dimensions": { + "length": 7.0, + "width": 12.0, + "height": 9.5 + }, + "warehouseLocation": { + "latitude": -78.75, + "longitude": 20.4 + } + } +``` diff --git a/learn/index.md b/learn/index.md new file mode 100644 index 00000000..058d46e1 --- /dev/null +++ b/learn/index.md @@ -0,0 +1,13 @@ +--- +layout: page +title: Learn +--- + +* [Getting Started Step-By-Step](./getting-started-step-by-step.md) which covers a classic product catalog description. +* [File System](./file-system.md) which uses JSON Schema to describe filesystem entries in a Unix-like file system. It is a little more in-depth / advanced than Getting Started. +* [Miscellaneous Examples](./miscellaneous-examples.md) +* Examples Collection + * [address.schema.json](./examples/address.schema.json) + * [calendar.schema.json](./examples/calendar.schema.json) + * [card.schema.json](./examples/card.schema.json) + * [geographical-location.schema.json](./examples/geographical-location.schema.json) diff --git a/learn/miscellaneous-examples.md b/learn/miscellaneous-examples.md new file mode 100644 index 00000000..37b0dee4 --- /dev/null +++ b/learn/miscellaneous-examples.md @@ -0,0 +1,159 @@ +--- +layout: page +title: Miscellaneous Examples +--- + +## Basic + +This example provides a typical minimum you are likely to see in JSON Schema. It contains: + +* [`$id`](http://json-schema.org/latest/json-schema-core.html#rfc.section.8.2) keyword +* [`$schema`](http://json-schema.org/latest/json-schema-core.html#rfc.section.7) keyword +* [`title`](http://json-schema.org/latest/json-schema-hypermedia.html#rfc.section.6.5.1) annotation keyword +* [`type`](http://json-schema.org/latest/json-schema-core.html#rfc.section.4.2.1) instance data model +* [`properties`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.4) validation keyword +* Three keys: `firstName`, `lastName` and `age` each with their own: + * [`description`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) annotation keyword. + * `type` instance data model (see above). +* [`minimum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.4) validation keyword on the `age` key. + +```json +{ + "$id": "https://example.com/person.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Person", + "type": "object", + "properties": { + "firstName": { + "type": "string", + "description": "The person's first name." + }, + "lastName": { + "type": "string", + "description": "The person's last name." + }, + "age": { + "description": "Age in years which must be equal to or greater than zero.", + "type": "integer", + "minimum": 0 + } + } +} +``` + +**Data** + +```json +{ + "firstName": "John", + "lastName": "Doe", + "age": 21 +} +``` + +## Describing geographical coordinates. + +This example introduces: + +* [`required`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.3) validation keyword +* [`minimum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.4) validation keyword +* [`maximum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.2) validation keyword + +```json +{ + "id": "https://example.com/geographical-location.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Longitude and Latitude Values", + "description": "A geographical coordinate.", + "required": [ "latitude", "longitude" ], + "type": "object", + "properties": { + "latitude": { + "type": "number", + "minimum": -90, + "maximum": 90 + }, + "longitude": { + "type": "number", + "minimum": -180, + "maximum": 180 + } + } +} +``` + +**Data** + +```json +{ + "latitude": 48.858093, + "longitude": 2.294694 +} +``` + +## Arrays of things + +Arrays are fundamental structures in JSON -- here we demonstrate a couple of ways they can be described: + +* An array of string values. +* An array of objects. + +We also introduce the following with this example: + +* [`definitions`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.9) keyword +* [`$ref`](http://json-schema.org/latest/json-schema-core.html#rfc.section.8.3) keyword + +```json +{ + "id": "https://example.com/arrays.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "A representation of a person, company, organization, or place", + "type": "object", + "properties": { + "fruits": { + "type": "array", + "items": { + "type": "string" + } + }, + "vegetables": { + "type": "array", + "items": { "$ref": "#/definitions/veggie" } + } + }, + "definitions": { + "veggie": { + "type": "object", + "required": [ "veggieName", "veggieLike" ], + "properties": { + "veggieName": { + "type": "string", + "description": "The name of the vegetable." + }, + "veggieLike": { + "type": "boolean", + "description": "Do I like this vegetable?" + } + } + } + } +} +``` + +**Data** + +```json +{ + "fruits": [ "apple", "orange", "pear" ], + "vegetables": [ + { + "veggieName": "potato", + "veggieLike": true + }, + { + "veggieName": "broccoli", + "veggieLike": false + } + ] +} +```