Home

Background

JSON Schema's format keyword

The format keyword has a particular role with regards to validation: while JSON Schema is primarily about analyzing the structure of JSON documents, format makes a semantic analysis of contents. Its value is a string called a format attribute, which helps further refine the contents of a given JSON value.

Here is an example which will check that the JSON value (if it is a string value, see below) is a valid URI:

    {
        "format": "uri"
    }

The draft also mentions that custom formats MAY be created. This package does exactly that: it creates an additional set of format attributes.

Note about validation

A format attribute targets only a certain set of primitive types among the seven types defined by the draft (array, boolean, integer, number, null, object and string). For instance, the uri format specifier above targets only string values. If the value to analyse is not understood by the format attribute, validation should succeed. So, if the value passed to the schema above is:

null

then validation succeeds (this is not a string value).

Custom format specifiers implemented by this package

base64

This specifier will determine whether a string value is a valid Base64 encoded string. Basically, "binary over the wire". VERY useful, imho...

Example:

"aTEHFJZWs6tjEyNI7AF4Tkjyz05Pfa0EQTHVke7tv7Ram0591Y1HDYHeObw0"

uuid

This format is meant to validate that a string value is a UUID. Example:

"6438850b-b33d-475f-95d7-8997606431a5"

md5, sha1, sha256, sha512

These specifiers validate the hexadecimal string representation of these different hashes. An example of (SHA1) input is:

"45c0c64fa1545a420e751847e941b0e7244171a7"

In particular, sha1 will accurately verify a git reference.

mac

This validates a MAC address. Note: it checks the form only, not whether that MAC address belongs to a machine, is broadcast etc. Sample input:

"a3:3E:ff:e3:01:fe"

json-pointer

This validates that a string value is a valid JSON Pointer (using JSON Pointer support in json-schema-core). Sample input:

"/x/~0foo/bar/-"

uri-template

This validates that a string value is a valid URI template (using the uri-template library). Sample input:

"http://my.site/search{?map*}"