Skip to content
This repository has been archived by the owner on Nov 3, 2023. It is now read-only.

Latest commit

 

History

History
325 lines (252 loc) · 9.07 KB

string.rst

File metadata and controls

325 lines (252 loc) · 9.07 KB
Raw

single: string

string

local

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

single: string; length single: maxLength single: minLength

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.

single: string; regular expression single: pattern

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) with Unicode support. 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:

single: string; format single: format

Format

The format keyword allows for basic semantic identification of certain kinds of string values that are commonly used. 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 will fail if, for example, a value with a date format isn't in a form that can be parsed as a date. This can allow values to be constrained beyond what the other tools in JSON Schema, including regular-expressions can do.

Note

Implementations may provide validation for only a subset of the built-in formats or do partial validation for a given format. For example, some implementations may consider a string an email if it contains a @, while others might do additional checks for other aspects of a well formed email address.

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.

single: format

Built-in formats

The following is the list of formats specified in the JSON Schema specification.

single: date-time single: time single: date single: format; date-time single: format; time single: format; date

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": Time, for example, 20:20:39+00:00
  • "date": Date, for example, 2018-11-13.
  • "duration": A duration as defined by the ISO 8601 ABNF for "duration". For example, P3D expresses a duration of 3 days.

single: email single: idn-email single: format; email single: format; idn-email

Email addresses

single: hostname single: idn-hostname single: format; hostname single: format; idn-hostname

Hostnames

single: ipv4 single: ipv6 single: format; ipv4 single: format; ipv6

IP Addresses

single: uuid single: uri single: uri-reference single: iri single: iri-reference single: format; uuid single: format; uri single: format; uri-reference single: format; iri single: format; iri-reference

Resource identifiers

  • "uuid": 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": A URI Reference (either a URI or a relative-reference), according to RFC3986, section 4.1.
  • "iri": The internationalized equivalent of a "uri", according to RFC3987.
  • "iri-reference": 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.

single: uri-template single: format; uri-template

URI template

  • "uri-template": 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.

single: json-pointer single: relative-json-pointer single: format; json-pointer single: format; relative-json-pointer

JSON Pointer

  • "json-pointer": A JSON Pointer, according to RFC6901. There is more discussion on the use of JSON Pointer within JSON Schema in structuring. 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": A relative JSON pointer.

single: regex single: format; regex

Regular Expressions

  • "regex": 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.