string

The string type is used for strings of text. It may contain Unicode characters.

In Python, "string" is analogous to the unicode type on Python 2.x, and the str type on Python 3.x.
In Ruby, "string" is analogous to the String type.
{ "type": "string" }

"This is a string"

Unicode characters:

"Déjà vu"

""

"42"

42

Length

The length of a string can be constrained using the minLength and maxLength keywords. For both keywords, the value must be a non-negative number.

{
  "type": "string",
  "minLength": 2,
  "maxLength": 3
}

"A"

"AB"

"ABC"

"ABCD"

Regular Expressions

The pattern keyword is used to restrict a string to a particular regular expression. The regular expression syntax is the one defined in JavaScript (ECMA 262 specifically). See Regular Expressions for more information.

Note

When defining the regular expressions, it’s important to note that the string is considered valid if the expression matches anywhere within the string. For example, the regular expression "p" will match any string with a p in it, such as "apple" not just a string that is simply "p". Therefore, it is usually less confusing, as a matter of course, to surround the regular expression in ^...$, for example, "^p$", unless there is a good reason not to do so.

The following example matches a simple North American telephone number with an optional area code:

{
   "type": "string",
   "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
}

"555-1212"

"(888)555-1212"

"(888)555-1212 ext. 532"

"(800)FLOWERS"

Format

The format keyword allows for basic semantic validation on certain kinds of string values that are commonly used. This allows values to be constrained beyond what the other tools in JSON Schema, including Regular Expressions can do.

Note

JSON Schema implementations are not required to implement this part of the specification, and many of them do not.

There is a bias toward networking-related formats in the JSON Schema specification, most likely due to its heritage in web technologies. However, custom formats may also be used, as long as the parties exchanging the JSON documents also exchange information about the custom format types. A JSON Schema validator will ignore any format type that it does not understand.

Built-in formats

The following is the list of 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.

Email addresses

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

Hostnames

IP Addresses

Resource identifiers

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

If the values in the schema have the ability to be relative to a particular source path (such as a link from a webpage), it is generally better practice to use "uri-reference" (or "iri-reference") rather than "uri" (or "iri"). "uri" should only be used when the path must be absolute.

Draft 4 only includes "uri", not "uri-reference". Therefore, there is some ambiguity around whether "uri" should accept relative paths.

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 the use of 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, which 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.