Type-specific keywords

The type keyword is fundamental to JSON Schema. It specifies the data type for a schema.

At its core, JSON Schema defines the following basic types:

• string
• number
• integer
• object
• array
• boolean
• null

These types have analogs in most programming languages, though they may go by different names.

The type keyword may either be a string or an array:

• If it's a string, it is the name of one of the basic types above.
• If it is an array, it must be an array of strings, where each string is the name of one of the basic types, and each element is unique. In this case, the JSON snippet is valid if it matches any of the given types.

Here is a simple example of using the type keyword:

schema

{ "type": "number" }

data

42

compliant to schema

data

42.0

compliant to schema

data

"42"

not compliant to schema

In the following example, we accept strings and numbers, but not structured data types:

schema

{ "type": ["number", "string"] }

data

42

compliant to schema

data

"Life, the universe, and everything"

compliant to schema

data

["Life", "the universe", "and everything"]

not compliant to schema

For each of these types, there are keywords that only apply to those types. For example, numeric types have a way of specifying a numeric range, that would not be applicable to other types. In this reference, these validation keywords are described along with each of their corresponding types in the following chapters.

Format

The format keyword conveys semantic information for values that may be difficult or impossible to describe using JSON Schema. Typically, this semantic information is described by other documents. The JSON Schema Validation specification defines several formats, but this keyword also allows schema authors to define their own formats.

For example, because JSON doesn't have a "DateTime" type, dates need to be encoded as strings. format allows the schema author to indicate that the string value should be interpreted as a date. By default, format is just an annotation and does not affect validation.

Optionally, validator implementations can provide a configuration option to enable format to function as an assertion rather than just an annotation. That means that validation fails when, for example, a value with a date format isn't in a form that can be parsed as a date. This allows values to be constrained beyond what other tools in JSON Schema, including Regular Expressions, can do.

The JSON Schema specification has a bias toward networking-related formats, likely due to its roots in web technologies. However, custom formats may also be used if the parties exchanging the JSON documents share information about the custom format types. A JSON Schema validator will ignore any format type it does not understand.

Built-in Formats

It should be noted that format is not limited because it only defines a specific set of valid values for formats. Users may define their own custom keywords to work with any specific data type, such as integer, double, float, etc. Below, we cover the commonly used string formats specified in the JSON Schema specification.

Dates and Times

Dates and times are represented in RFC 3339, section 5.6. This is a subset of the date format also commonly known as ISO8601 format.

• "date-time": Date and time together, for example, 2018-11-13T20:20:39+00:00.
• "time":
  New in draft 7
  Time, for example, 20:20:39+00:00.
• "date":
  New in draft 7
  Date, for example, 2018-11-13.
• "duration":
  New in draft 2019-09
  A duration as defined by the ISO 8601 ABNF for "duration". For example, P3D expresses a duration of 3 days.

Email Addresses

• "email": Internet email address, see RFC 5321, section 4.1.2.
• "idn-email":
  New in draft 7
  The internationalized form of an Internet email address, see RFC 6531.

Hostnames

• "hostname": Internet host name, see RFC 1123, section 2.1.
• "idn-hostname":
  New in draft 7
  An internationalized Internet host name, see RFC5890, section 2.3.2.3.

IP Addresses

• "ipv4": IPv4 address, according to dotted-quad ABNF syntax as defined in RFC 2673, section 3.2.
• "ipv6": IPv6 address, as defined in RFC 2373, section 2.2.

Resource Identifiers

• "uuid":
  New in draft 2019-09
  A Universally Unique Identifier as defined by RFC 4122. Example: 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a.
• "uri": A universal resource identifier (URI), according to RFC3986.
• "uri-reference":
  New in draft 6
  A URI Reference (either a URI or a relative-reference), according to RFC3986, section 4.1.
• "iri":
  New in draft 7
  The internationalized equivalent of a "uri", according to RFC3987.
• "iri-reference":
  New in draft 7
  The internationalized equivalent of a "uri-reference", according to RFC3987.

URI Template

• "uri-template":
  New in draft 6
  A URI Template (of any level) according to RFC6570. If you don't already know what a URI Template is, you probably don't need this value.

JSON Pointer

• "json-pointer":
  New in draft 6
  A JSON Pointer, according to RFC6901. There is more discussion on using JSON Pointer within JSON Schema in Structuring a complex schema. Note that this should be used only when the entire string contains only JSON Pointer content, e.g., /foo/bar. JSON Pointer URI fragments, e.g., #/foo/bar/ should use "uri-reference".
• "relative-json-pointer":
  New in draft 7
  A relative JSON pointer.

Regular Expressions

• "regex":
  New in draft 7
  A regular expression that should be valid according to the ECMA 262 dialect. Be careful, in practice, JSON Schema validators are only required to accept the safe subset of regular expressions described elsewhere in this document.