From a93ab9846061ea827b78e7e0db182af1393b947a Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Sun, 19 Mar 2017 18:10:35 -0500 Subject: [PATCH 1/2] Convert other html pages to Markdown --- documentation.html | 68 ----- documentation.md | 41 ++++ example1.html => example1.md | 143 ++++++----- example2.html | 464 ----------------------------------- example2.md | 409 ++++++++++++++++++++++++++++++ examples.html | 38 --- examples.md | 39 +++ index.html | 64 ----- index.md | 70 ++++++ 9 files changed, 628 insertions(+), 708 deletions(-) delete mode 100644 documentation.html create mode 100644 documentation.md rename example1.html => example1.md (50%) delete mode 100644 example2.html create mode 100644 example2.md delete mode 100644 examples.html create mode 100644 examples.md delete mode 100644 index.html create mode 100644 index.md diff --git a/documentation.html b/documentation.html deleted file mode 100644 index 1c2966b1..00000000 --- a/documentation.html +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: page ---- - -

Specification

-
-

The latest Internet-Draft at the IETF is v5, published 2016-10-13. - (Due to a change in authorship the I-D numbering has been reset). - The specification is split into three parts, Core, Validation, and Hyper-Schema:

- - - - - - - - - - - - - -
JSON Schema Coredefines the basic foundation of JSON Schema
JSON Schema Validationdefines the validation keywords of JSON Schema
JSON Hyper-Schemadefines the hyper-media keywords of JSON Schema
-

They are also available on the IETF main site: core (draft-wright-json-schema-00), validation (draft-wright-json-schema-validation-00) and hyper-schema (draft-wright-json-schema-hyperschema-00). -

-

For previous versions of the specification, please see the Specification Links page on our github wiki. -

-
- -

Meta-schemas

-
-

The meta-schemas are the schemas which define the JSON Schema and Hyper-Schema formats.

-

The latest meta-schema is draft-04. A future release with additional keywords will be published in the near future.

- - - - - - - - - -
Core/Validation Meta-SchemaUsed for schemas written for pure validation.
Hyper Meta-SchemaUsed for schemas written for validation and hyper-linking.
-
- -

Standard schemas

-
-

These sample schemas describe simple data structures which can be expressed as JSON: -

- - - - - - - - - - - - - - - - - -
Geographic Coordinatea location as longitude and latitude
Carda microformat-style representation of a person, company, organization, or place
Calendara microformat-style representation of an event
Addressa microformat-style representation of a street address
-
diff --git a/documentation.md b/documentation.md new file mode 100644 index 00000000..32ee6821 --- /dev/null +++ b/documentation.md @@ -0,0 +1,41 @@ +--- +layout: page +--- + +Specification +------------- + +The latest Internet-Draft at the IETF is v5, published 2016-10-13. (Due to a change in authorship the I-D numbering has been reset). The specification is split into three parts, Core, Validation, and Hyper-Schema: + +|--------------------------------------------------------------|-------------------------------------------------| +| [JSON Schema Core](latest/json-schema-core.html) | defines the basic foundation of JSON Schema | +| [JSON Schema Validation](latest/json-schema-validation.html) | defines the validation keywords of JSON Schema | +| [JSON Hyper-Schema](latest/json-schema-hypermedia.html) | defines the hyper-media keywords of JSON Schema | + +They are also available on the IETF main site: [core (draft-wright-json-schema-00)](http://tools.ietf.org/html/draft-wright-json-schema-00), [validation (draft-wright-json-schema-validation-00)](http://tools.ietf.org/html/draft-wright-json-schema-validation-00) and [hyper-schema (draft-wright-json-schema-hyperschema-00)](http://tools.ietf.org/html/draft-wright-json-schema-hyperschema-00). + +For previous versions of the specification, please see the [Specification Links](https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links) page on our github wiki. + +Meta-schemas +------------ + +The meta-schemas are the schemas which define the JSON Schema and Hyper-Schema formats. + +The latest meta-schema is draft-04. A future release with additional keywords will be published in the near future. + +|--------------------------------------------------------------|------------------------------------------------------------| +| [Core/Validation Meta-Schema](http://json-schema.org/schema) | Used for schemas written for pure validation. | +| [Hyper Meta-Schema](http://json-schema.org/hyper-schema) | Used for schemas written for validation and hyper-linking. | + +Standard schemas +---------------- + +These sample schemas describe simple data structures which can be expressed as JSON: + +|-----------------------------------------------------|---------------------------------------------------------------------------------| +| [Geographic Coordinate](http://json-schema.org/geo) | a location as longitude and latitude | +| [Card](http://json-schema.org/card) | a microformat-style representation of a person, company, organization, or place | +| [Calendar](http://json-schema.org/calendar) | a microformat-style representation of an event | +| [Address](http://json-schema.org/address) | a microformat-style representation of a street address | + + diff --git a/example1.html b/example1.md similarity index 50% rename from example1.html rename to example1.md index 86a980df..429b991e 100644 --- a/example1.html +++ b/example1.md @@ -2,69 +2,65 @@ layout: page --- -

Example data

-
-

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 data +------------ -

Example JSON data for a product API

-

An example product in this API is:

+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
 {
     "id": 1,
     "name": "A green door",
     "price": 12.50,
     "tags": ["home", "green"]
 }
-
+``` -

While generally straightforward, that example leaves some open questions. For example, one may ask:

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

-
+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:

+Starting the schema +------------------- -

+To start a schema definition, let's begin with a basic JSON schema:
+
+```json
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "Product",
     "description": "A product from Acme's catalog",
     "type": "object"
 }
-
+``` + +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 above schema has four properties called keywords. +The *type* keyword defines the first constraint on our JSON data: it has to be a JSON Object. - 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).

+Finally, the *$schema* keyword states that this schema is written according to the draft v4 specification. -

The type keyword defines the first constraint on our JSON data: it has to be a JSON - Object.

+Defining the properties +----------------------- -

Finally, the $schema keyword states that this schema is written according to the draft - v4 specification.

-
+Next let's answer our previous questions about this API, starting with id. -

Defining the properties

-
-

Next let's answer our previous questions about this API, starting with id.

+### What is 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.

+*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:

-

+In JSON Schema terms, we can update our schema to:
+
+```json
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "Product",
@@ -78,13 +74,13 @@ 
What is id?

     },
     "required": ["id"]
 }
-
+``` + +### Is name required? -

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:

+*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
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "Product",
@@ -102,12 +98,13 @@ 
Is name required?

     },
     "required": ["id", "name"]
 }
-
+``` + +### Can price be 0? -

Can price be 0?

-

According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify exclusiveMinimum. Therefore we can update our schema with price:

+According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify *exclusiveMinimum*. Therefore we can update our schema with *price*: -

+```json
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "Product",
@@ -130,25 +127,20 @@ 
Can price be 0?

     },
     "required": ["id", "name", "price"]
 }
-
+``` -

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. According - to Acme's docs, all tags must be strings, but you aren't required to specify - tags. We simply leave tags out of the list of required properties.

+### Are all tags strings? -

However, Acme's docs add two constraints:

+Finally, we come to the *tags* property. Unlike the previous properties, tags have many values, and is represented as a JSON array. According to Acme's docs, all tags must be strings, but you aren't required to specify tags. We simply leave *tags* out of the list of required properties. - +However, Acme's docs add two constraints: -

The first constraint can be added with minItems, and the second one by - specifying uniqueItems as being true:

+- 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
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "Product",
@@ -179,17 +171,20 @@ 
Are all tags strings?

     },
     "required": ["id", "name", "price"]
 }
-
-
+``` + +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). -

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.

-

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.

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

Set of products:

-

+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
 [
     {
         "id": 2,
@@ -221,10 +216,11 @@ 
Set of products:

         }
     }
 ]
-
+``` + +### Set of products schema: -

Set of products schema:

-

+```json
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "Product set",
@@ -270,6 +266,5 @@ 
Set of products schema:

         "required": ["id", "name", "price"]
     }
 }
-
-
+``` diff --git a/example2.html b/example2.html deleted file mode 100644 index 292574ec..00000000 --- a/example2.html +++ /dev/null @@ -1,464 +0,0 @@ ---- -layout: page ---- - -

Purpose

-
-

This example shows a possible JSON representation of a hypothetical machine's mount points as - represented in an /etc/fstab file.

- -

An entry in the fstab file can have many different forms. Here is a possible representation of a - full fstab:

- -

-{
-    "/": {
-        "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"
-        }
-    }
-}
-
- -

Not all constraints to an fstab file can be modeled using JSON Schema alone; however, it can - already 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:

- - - -

We also want the schema to be regarded as a draft v4 schema, we must therefore specify - $schema:

- -

-{
-    "$schema": "http://json-schema.org/draft-04/schema#",
-    "type": "object",
-    "properties": {
-        "/": {}
-    },
-    "patternProperties": {
-        "^(/[^/]+)+$": {}
-    },
-    "additionalProperties": false,
-    "required": [ "/" ]
-}
-
- -

Note how the valid paths constraint is enforced here:

- - - -

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:

- -

-{
-    "id": "http://some.site.somewhere/entry-schema#",
-    "$schema": "http://json-schema.org/draft-04/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": {}
-    }
-}
-
- -

You should already be familiar with some of the constraints:

- - - -

There are a couple of novelties:

- - - -

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:

- - - -

With these added constraints, the schema now looks like this:

- -

-{
-    "id": "http://some.site.somewhere/entry-schema#",
-    "$schema": "http://json-schema.org/draft-04/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": {}
-    }
-}
-
- -

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:

- -

-{
-    "properties": {
-        "type": { "enum": [ "disk" ] },
-        "device": {
-            "type": "string",
-            "pattern": "^/dev/[^/]+(/[^/]+)*$"
-        }
-    },
-    "required": [ "type", "device" ],
-    "additionalProperties": false
-}
-
- -

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:

- -

-{
-    "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 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:

- -

-{
-    "properties": {
-        "type": { "enum": [ "nfs" ] },
-        "remotePath": {
-            "type": "string",
-            "pattern": "^(/[^/]+)+$"
-        },
-        "server": {
-            "type": "string",
-            "oneOf": [
-                { "format": "host-name" },
-                { "format": "ipv4" },
-                { "format": "ipv6" }
-            ]
-        }
-    },
-    "required": [ "type", "server", "remotePath" ],
-    "additionalProperties": false
-}
-
-
- -

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:

- -

-{
-    "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:

-

- -

-{
-    "id": "http://some.site.somewhere/entry-schema#",
-    "$schema": "http://json-schema.org/draft-04/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": "host-name" },
-                        { "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
-        }
-    }
-}
-
-
- -

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:

- -

-{
-    "$schema": "http://json-schema.org/draft-04/schema#",
-    "type": "object",
-    "properties": {
-        "/": { "$ref": "http://some.site.somewhere/entry-schema#" }
-    },
-    "patternProperties": {
-        "^(/[^/]+)+$": { "$ref": "http://some.site.somewhere/entry-schema#" }
-    },
-    "additionalProperties": false,
-    "required": [ "/" ]
-}
-
-
- -

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:

- - - -

As an exercise, you can always try and 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:

- - -
diff --git a/example2.md b/example2.md new file mode 100644 index 00000000..be42c5f8 --- /dev/null +++ b/example2.md @@ -0,0 +1,409 @@ +--- +layout: page +--- + +Purpose +------- + +This example shows a possible JSON representation of a hypothetical machine's mount points as represented in an `/etc/fstab` file. + +An entry in the fstab file can have many different forms. Here is a possible representation of a full fstab: + +```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" + } + } +} +``` + +Not all constraints to an fstab file can be modeled using JSON Schema alone; however, it can already 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 v4 schema, we must therefore specify *$schema*: + +```json +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "properties": { + "/": {} + }, + "patternProperties": { + "^(/[^/]+)+$": {} + }, + "additionalProperties": false, + "required": [ "/" ] +} +``` + +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 +{ + "id": "http://some.site.somewhere/entry-schema#", + "$schema": "http://json-schema.org/draft-04/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": {} + } +} +``` + +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 +{ + "id": "http://some.site.somewhere/entry-schema#", + "$schema": "http://json-schema.org/draft-04/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": {} + } +} +``` + +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 +{ + "properties": { + "type": { "enum": [ "disk" ] }, + "device": { + "type": "string", + "pattern": "^/dev/[^/]+(/[^/]+)*$" + } + }, + "required": [ "type", "device" ], + "additionalProperties": false +} +``` + +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 +{ + "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* 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 +{ + "properties": { + "type": { "enum": [ "nfs" ] }, + "remotePath": { + "type": "string", + "pattern": "^(/[^/]+)+$" + }, + "server": { + "type": "string", + "oneOf": [ + { "format": "host-name" }, + { "format": "ipv4" }, + { "format": "ipv6" } + ] + } + }, + "required": [ "type", "server", "remotePath" ], + "additionalProperties": false +} +``` + +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 +{ + "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://some.site.somewhere/entry-schema#", + "$schema": "http://json-schema.org/draft-04/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": "host-name" }, + { "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 + } + } +} +``` + +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 +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "type": "object", + "properties": { + "/": { "$ref": "http://some.site.somewhere/entry-schema#" } + }, + "patternProperties": { + "^(/[^/]+)+$": { "$ref": "http://some.site.somewhere/entry-schema#" } + }, + "additionalProperties": false, + "required": [ "/" ] +} +``` + +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 and 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 v4 syntax, but not all tools support draft v4 (in fact, most don't support it). + + diff --git a/examples.html b/examples.html deleted file mode 100644 index df2169fc..00000000 --- a/examples.html +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: page ---- - -

Basic example

-
-

Here is a basic example of a JSON Schema: -


-{
-	"title": "Person",
-	"type": "object",
-	"properties": {
-		"firstName": {
-			"type": "string"
-		},
-		"lastName": {
-			"type": "string"
-		},
-		"age": {
-			"description": "Age in years",
-			"type": "integer",
-			"minimum": 0
-		}
-	},
-	"required": ["firstName", "lastName"]
-}
-
-
- -

Walkthroughs

-
-

The two examples below are step-by-step guides into building a schema: -

-

The Space Telescope Science Institute has also published an guide aimed at schema authors. -

diff --git a/examples.md b/examples.md new file mode 100644 index 00000000..1a6ca57d --- /dev/null +++ b/examples.md @@ -0,0 +1,39 @@ +--- +layout: page +--- + +Basic example +------------- + +Here is a basic example of a JSON Schema: + +```json +{ + "title": "Person", + "type": "object", + "properties": { + "firstName": { + "type": "string" + }, + "lastName": { + "type": "string" + }, + "age": { + "description": "Age in years", + "type": "integer", + "minimum": 0 + } + }, + "required": ["firstName", "lastName"] +} +``` + +Walkthroughs +------------ + +The two examples below are step-by-step guides into building a schema: + +- [a simple example](example1.html) which covers a classical product catalog description. +- [a more advanced example](example2.html), 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 an [guide aimed at schema authors](http://spacetelescope.github.io/understanding-json-schema/). diff --git a/index.html b/index.html deleted file mode 100644 index cd6b5019..00000000 --- a/index.html +++ /dev/null @@ -1,64 +0,0 @@ ---- -layout: page -title: JSON Schema -permalink: / ---- - -

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

- -

Advantages

-
-

JSON Schema

- -
-
-

JSON Hyper-Schema

- -
-
- - -

Quickstart

- -

The JSON document being validated or described we call the instance, and the document containing the description is called the schema.

- -

The most basic schema is a blank JSON object, which constrains nothing, allows anything, and describes nothing:

- -
{}
- -

You can apply constraints on an instance by adding validation keywords to the schema. For instance, the "type" keyword can be used to restrict an instance to an object, array, string, number, boolean, or null:

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

-
-

Interested? Check out: -

-

Questions? Feeling helpful? Get involved on: -

-
diff --git a/index.md b/index.md new file mode 100644 index 00000000..8da761fa --- /dev/null +++ b/index.md @@ -0,0 +1,70 @@ +--- +layout: page +title: JSON Schema +permalink: / +--- + +**JSON Schema** is a vocabulary that allows you to **annotate** and **validate** JSON documents. + +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 +
+ +
+ +### JSON Hyper-Schema + +- describes your existing API - no new structures required +- links (including [URI Templates](http://tools.ietf.org/html/rfc6570) for target URIs) +- forms - specify a JSON Schema for the desired data + +
+ +
+ +Quickstart +---------- + +The JSON document being validated or described we call the *instance*, and the document containing the description is called the *schema*. + +The most basic schema is a blank JSON object, which constrains nothing, allows anything, and describes nothing: + +```json +{} +``` + +You can apply constraints on an instance by adding validation keywords to the schema. For instance, the "type" keyword can be used to restrict an instance to an object, array, string, number, boolean, or null: + +```json +{"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 +---- + +Interested? Check out: + +- the [specification](documentation.html) +- some [examples](examples.html) +- this [excellent guide](http://spacetelescope.github.io/understanding-json-schema/) for schema authors, from the [Space Telescope Science Institute](http://www.stsci.edu/) +- the growing list of [JSON (Hyper-)Schema software](implementations.html) + +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 [IRC channel](irc://chat.freenode.net/json-schema) ([Freenode Webchat](https://webchat.freenode.net/?channels=json-schema)) + + From 2dd466478ba81437fda9d52775759806028186e4 Mon Sep 17 00:00:00 2001 From: Adam Voss Date: Thu, 23 Mar 2017 21:13:46 -0500 Subject: [PATCH 2/2] Use .md extension for links within repository This way they work from both GitHub and the website. --- _config.yml | 3 +++ examples.md | 4 ++-- index.md | 6 +++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/_config.yml b/_config.yml index d8130891..ac4cbf71 100644 --- a/_config.yml +++ b/_config.yml @@ -29,3 +29,6 @@ collections: docs: output: true permalink: "/:title:output_ext" + +gems: + - jekyll-relative-links diff --git a/examples.md b/examples.md index 1a6ca57d..d8d8e993 100644 --- a/examples.md +++ b/examples.md @@ -33,7 +33,7 @@ Walkthroughs The two examples below are step-by-step guides into building a schema: -- [a simple example](example1.html) which covers a classical product catalog description. -- [a more advanced example](example2.html), using JSON Schema to describe filesystem entries in a Unix-like /etc/fstab file. +- [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 an [guide aimed at schema authors](http://spacetelescope.github.io/understanding-json-schema/). diff --git a/index.md b/index.md index 8da761fa..ad0e121d 100644 --- a/index.md +++ b/index.md @@ -56,10 +56,10 @@ More Interested? Check out: -- the [specification](documentation.html) -- some [examples](examples.html) +- the [specification](documentation.md) +- some [examples](examples.md) - this [excellent guide](http://spacetelescope.github.io/understanding-json-schema/) for schema authors, from the [Space Telescope Science Institute](http://www.stsci.edu/) -- the growing list of [JSON (Hyper-)Schema software](implementations.html) +- the growing list of [JSON (Hyper-)Schema software](implementations.md) Questions? Feeling helpful? Get involved on: