example2.html

---
layout: page
---

<h2>Purpose</h2>
<div class="block">
    <p>This example shows a possible JSON representation of a hypothetical machine's mount points as
    represented in an <code>/etc/fstab</code> file.</p>

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

<pre class="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"
        }
    }
}
</pre>

    <p>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.</p>
</div>

<h2>Base schema</h2>
<div class="block">
    <p>We will start with a base schema expressing the following constraints:</p>

    <ul>
        <li>the list of entries is a JSON object;</li>
        <li>the member names (or property names) of this object must all be valid, absolute paths;</li>
        <li>there must be an entry for the root filesystem (ie, <code>/</code>).</li>
    </ul>

    <p>We also want the schema to be regarded as a draft v4 schema, we must therefore specify
    <em>$schema</em>:</p>

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

    <p>Note how the valid paths constraint is enforced here:</p>

    <ul>
        <li>we have a <em>properties</em> keyword with only a <code>/</code> entry;</li>
        <li>we use <em>patternProperties</em> to match other property names via a regular
        expression (note that it does not match <code>/</code>);</li>
        <li>as <em>additionalProperties</em> is false, it constrains object properties to be either
        <code>/</code> or to match the regular expression.</li>
    </ul>

    <p>You will notice that the regular expression is explicitly anchored (with <code>^</code> and
    <code>$</code>): in JSON Schema, regular expressions (in <em>patternProperties</em> and in
    <em>pattern</em>) are not anchored by default.</p>

    <p>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.</p>
</div>

<h2>The entry schema - starting out</h2>
<div class="block">
    <p>Here again we will proceed step by step. We will start with the global structure of our schema, which will be as such:</p>

<pre class="json-schema">
{
    "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": {}
    }
}
</pre>

    <p>You should already be familiar with some of the constraints:</p>

    <ul>
        <li>an fstab entry must be an object (<code>"type": "object"</code>);</li>
        <li>it must have one property with name <em>storage</em> (<code>"required": [ "storage" ]</code>);</li>
        <li>the <em>storage</em> property must also be an object.</li>
    </ul>

    <p>There are a couple of novelties:</p>

    <ul>
        <li>you will notice the appearance of JSON References, via the <em>$ref</em> keyword; here, all
        references used are local to the schema, and the fragment part is a URI encoded JSON Pointer;</li>
        <li>you will notice the appearance of an <em>id</em>: this is the URI of this resource; we assume
        here that this URI is the actual URI of this schema;</li>
        <li>the <em>oneOf</em> 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;</li>
        <li>finally, the <em>definitions</em> keyword is a standardized placeholder in which you can define
        inline subschemas to be used in a schema.</li>
    </ul>

    <h3>The <em>fstype</em>, <em>options</em> and <em>readonly</em> properties</h3>
</div>

<h2>The entry schema - adding constraints</h2>
<div class="block">
    <p>Let's now extend this skeleton to add constraints to these three properties. Note that none of
    them are required:</p>

    <ul>
        <li>we will pretend that we only support <code>ext3</code>, <code>ext4</code> and <code>btrfs</code> as
        filesystem types;</li>
        <li><em>options</em> 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;</li>
        <li><em>readonly</em> must be a boolean.</li>
    </ul>

    <p>With these added constraints, the schema now looks like this:</p>

<pre class="json-schema">
{
    "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": {}
    }
}
</pre>

    <p>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.</p>
</div>

<h2>The <em>diskDevice</em> storage type</h2>
<div class="block">
    <p>This storage type has two required properties, <em>type</em> and <em>device</em>. The type can
    only be <em>disk</em>, and the device must be an absolute path starting with <em>/dev</em>. No other
    properties are allowed:</p>

<pre class="json-schema">
{
    "properties": {
        "type": { "enum": [ "disk" ] },
        "device": {
            "type": "string",
            "pattern": "^/dev/[^/]+(/[^/]+)*$"
        }
    },
    "required": [ "type", "device" ],
    "additionalProperties": false
}
</pre>

    <p>You will have noted that we need not specify that <em>type</em> must be a string: the constraint
    described by <em>enum</em> is enough.</p>
</div>

<h2>The <em>diskUUID</em> storage type</h2>
<div class="block">

    <p>This storage type has two required properties, <em>type</em> and <em>label</em>. The type can
    only be <em>disk</em>, and the label must be a valid UUID. No other properties are allowed:</p>

<pre class="json-schema">
{
    "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
}
</pre>
</div>

<h2>The <em>nfs</em> storage type</h2>
<div class="block">
    <p>This storage type has three required properties: <em>type</em>, <em>server</em> and
    <em>remotePath</em>. What is more, the server may be either a host name, an IPv4 address or an IPv6
    address.</p>

    <p>For the constraints on <em>server</em>, we use a new keyword: <em>format</em>. While it is not
    required that <em>format</em> be supported, we will suppose that it is here:</p>

<pre class="json-schema">
{
    "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
}
</pre>
</div>

<h2>The <em>tmpfs</em> storage type</h2>
<div class="block">
    <p>This storage type has two required properties: <em>type</em> and <em>sizeInMB</em>. The size can
    only be an integer. What is more, we will require that the size be between 16 and 512,
    inclusive:</p>

<pre class="json-schema">
{
    "properties": {
        "type": { "enum": [ "tmpfs" ] },
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512
        }
    },
    "required": [ "type", "sizeInMB" ],
    "additionalProperties": false
}
</pre>
</div>

<h2>The full entry schema</h2>
<div class="block">
    <p>The resulting schema is quite large:</p>
    <div class="show-hide" data-target="full-entry-schema"></div><br>

<pre class="json-schema" id="full-entry-schema">
{
    "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
        }
    }
}
</pre>
</div>

<h2>Plugging this into our main schema</h2>
<div class="block">
    <p>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: </p>

<pre class="json-schema">
{
    "$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": [ "/" ]
}
</pre>
</div>

<h2>Wrapping up</h2>
<div class="block">
    <p>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.</p>

    <h3>The schema can be improved</h3>

    <p>This is only an example for learning purposes. Some additional constraints could be described.
    For instance:</p>

    <ul>
    <li>it makes no sense for <code>/</code> to be mounted on a tmpfs filesystem;</li>
    <li>it makes no sense to specify the filesystem type if the storage is either NFS or tmpfs.</li>
    </ul>

    <p>As an exercise, you can always try and add these constraints. It would probably require splitting
    the schema further.</p>

    <h3>Not all constraints can be expressed</h3>

    <p>JSON Schema limits itself to describing the structure of JSON data, it cannot express functional
    constraints.</p>

    <p>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.</p>

    <h3>Tools have varying JSON Schema support</h3>

    <p>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:</p>

    <ul>
    <li><em>format</em> support is optional, and as such other tools may ignore this keyword: this can
    lead to a different validation outcome for the same data;</li>
    <li>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;</li>
    <li>it uses <em>$schema</em> to express the need to use draft v4 syntax, but not all tools support
    draft v4 (in fact, most don't support it).</li>
    </ul>
</div>