diff --git a/pages/understanding-json-schema/reference/string.md b/pages/understanding-json-schema/reference/string.md index a91cf75ca..3bdecaeb8 100644 --- a/pages/understanding-json-schema/reference/string.md +++ b/pages/understanding-json-schema/reference/string.md @@ -115,129 +115,3 @@ with an optional area code: // props { "indent": true, "valid": false } "(800)FLOWERS" ``` - -## 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 effect validation. - -Optionally, validator [implementations](../../learn/glossary#implementation) 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](../../understanding-json-schema/reference/regular_expressions) can -do. - -> 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. - -### Built-in formats[#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](https://tools.ietf.org/html/rfc3339#section-5.6). This is a subset -of the date format also commonly known as [ISO8601 format](https://www.iso.org/iso-8601-date-and-time-format.html). - -- `"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\"](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). - For example, `P3D` expresses a duration of 3 days. - - - -#### Email addresses - -- `"email"`: Internet email address, see [RFC 5321, section 4.1.2](http://tools.ietf.org/html/rfc5321#section-4.1.2). -- `"idn-email"`: The internationalized form of an Internet email - address, see [RFC 6531](https://tools.ietf.org/html/rfc6531). - - - -#### Hostnames - -- `"hostname"`: Internet host name, see [RFC 1123, section 2.1](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1). -- `"idn-hostname"`: An internationalized Internet host name, see - [RFC5890, section 2.3.2.3](https://tools.ietf.org/html/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](http://tools.ietf.org/html/rfc2673#section-3.2). -- `"ipv6"`: IPv6 address, as defined in [RFC 2373, section 2.2](http://tools.ietf.org/html/rfc2373#section-2.2). - - - -#### Resource identifiers - -- `"uuid"`: A Universally Unique Identifier as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). Example: - `3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a` -- `"uri"`: A universal resource identifier (URI), according to - [RFC3986](http://tools.ietf.org/html/rfc3986). -- `"uri-reference"`: A URI Reference (either a URI or a - relative-reference), according to [RFC3986, section 4.1](http://tools.ietf.org/html/rfc3986#section-4.1). -- `"iri"`: The internationalized equivalent of a \"uri\", according to - [RFC3987](https://tools.ietf.org/html/rfc3987). -- `"iri-reference"`: The internationalized equivalent of a - \"uri-reference\", according to - [RFC3987](https://tools.ietf.org/html/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. - - - -#### URI template - -- `"uri-template"`: A URI Template (of any level) according to - [RFC6570](https://tools.ietf.org/html/rfc6570). If you don\'t - already know what a URI Template is, you probably don\'t need this - value. - - - -#### JSON Pointer - -- `"json-pointer"`: A JSON Pointer, according to - [RFC6901](https://tools.ietf.org/html/rfc6901). There is more - discussion on the use of JSON Pointer within JSON Schema in - [Structuring a complex schema](../../understanding-json-schema/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](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01). - - - -#### Regular Expressions - -- `"regex"`: A regular expression, which should be valid according to - the [ECMA 262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) - [dialect](../../learn/glossary#dialect). - -Be careful, in practice, JSON schema validators are only required to -accept the safe subset of [regular expressions](../../understanding-json-schema/reference/regular_expressions) described elsewhere in this document. diff --git a/pages/understanding-json-schema/reference/type.md b/pages/understanding-json-schema/reference/type.md index ed2fd52ce..f385b0c46 100644 --- a/pages/understanding-json-schema/reference/type.md +++ b/pages/understanding-json-schema/reference/type.md @@ -175,3 +175,129 @@ 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[#format] + +The `format` keyword allows for basic semantic identification of certain +kinds of values that are commonly used. or user could define its own format and use them alongside + +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 effect validation. + +Optionally, validator [implementations](../../learn/glossary#implementation) 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 can allow values to be constrained beyond what the other +tools in JSON Schema, including [Regular Expressions](../../understanding-json-schema/reference/regular_expressions) can +do. + +> 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. + +### Built-in formats[#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](https://tools.ietf.org/html/rfc3339#section-5.6). This is a subset +of the date format also commonly known as [ISO8601 format](https://www.iso.org/iso-8601-date-and-time-format.html). + +- `"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\"](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). + For example, `P3D` expresses a duration of 3 days. + + + +#### Email addresses + +- `"email"`: Internet email address, see [RFC 5321, section 4.1.2](http://tools.ietf.org/html/rfc5321#section-4.1.2). +- `"idn-email"`: The internationalized form of an Internet email + address, see [RFC 6531](https://tools.ietf.org/html/rfc6531). + + + +#### Hostnames + +- `"hostname"`: Internet host name, see [RFC 1123, section 2.1](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1). +- `"idn-hostname"`: An internationalized Internet host name, see + [RFC5890, section 2.3.2.3](https://tools.ietf.org/html/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](http://tools.ietf.org/html/rfc2673#section-3.2). +- `"ipv6"`: IPv6 address, as defined in [RFC 2373, section 2.2](http://tools.ietf.org/html/rfc2373#section-2.2). + + + +#### Resource identifiers + +- `"uuid"`: A Universally Unique Identifier as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). Example: + `3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a` +- `"uri"`: A universal resource identifier (URI), according to + [RFC3986](http://tools.ietf.org/html/rfc3986). +- `"uri-reference"`: A URI Reference (either a URI or a + relative-reference), according to [RFC3986, section 4.1](http://tools.ietf.org/html/rfc3986#section-4.1). +- `"iri"`: The internationalized equivalent of a \"uri\", according to + [RFC3987](https://tools.ietf.org/html/rfc3987). +- `"iri-reference"`: The internationalized equivalent of a + \"uri-reference\", according to + [RFC3987](https://tools.ietf.org/html/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. + + + +#### URI template + +- `"uri-template"`: A URI Template (of any level) according to + [RFC6570](https://tools.ietf.org/html/rfc6570). If you don\'t + already know what a URI Template is, you probably don\'t need this + value. + + + +#### JSON Pointer + +- `"json-pointer"`: A JSON Pointer, according to + [RFC6901](https://tools.ietf.org/html/rfc6901). There is more + discussion on using JSON Pointer within JSON Schema in + [Structuring a complex schema](../../understanding-json-schema/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](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01). + + + +#### Regular Expressions + +- `"regex"`: A regular expression that should be valid according to + the [ECMA 262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) + [dialect](../../learn/glossary#dialect). + +Be careful, in practice, JSON schema validators are only required to +accept the safe subset of [regular expressions](../../understanding-json-schema/reference/regular_expressions) described elsewhere in this document.