Skip to content

Validate formats

Each format has an is function, which returns whether a value is valid for the format:

TypeScript
import { isEmail, isIPv4 } from "@hyperjump/json-schema-formats";
isEmail("[email protected]"); // true
isIPv4("256.0.0.1"); // false

JSON Schema’s formats apply only to strings, so their functions take only strings. Check that a value is a string before you call one:

TypeScript
const validateEmail = (value: unknown) =>
typeof value !== "string" || isEmail(value);

The following table shows the function for each format, and the specification that defines what’s valid:

Format Function Specification
date isDate RFC 3339 full-date
time isTime RFC 3339 full-time
date-time isDateTime RFC 3339 date-time
duration isDuration RFC 3339 duration
email isEmail RFC 5321 Mailbox
idn-email isIdnEmail RFC 6531 Mailbox
hostname isAsciiIdn, or isHostname in draft-04 to draft-06 RFC 5890 A-labels and NR-LDH labels, or RFC 1123
idn-hostname isIdn RFC 5890 and UTS #46
ipv4 isIPv4 RFC 2673 dotted quad
ipv6 isIPv6 RFC 4291
uri isUri RFC 3986 URI
uri-reference isUriReference RFC 3986 URI-reference
iri isIri RFC 3987 IRI
iri-reference isIriReference RFC 3987 IRI-reference
uuid isUuid RFC 4122 UUID
uri-template isUriTemplate RFC 6570 URI-Template
json-pointer isJsonPointer RFC 6901 json-pointer
relative-json-pointer isRelativeJsonPointer draft-bhutton-relative-json-pointer-00
regex isRegex ECMA-262

The functions for URIs and IRIs check a value with the rules of its scheme, if it’s a scheme that they know. For more information, see URIs and IRIs.

hostname means something different in different versions of JSON Schema, so it has two functions. In draft-04 to draft-06, hostname is an RFC 1123 hostname, which is isHostname. From draft-07, it’s an internationalized hostname that has only ASCII characters, which is isAsciiIdn. isAsciiIdn rejects some hostnames that isHostname accepts, like ab--c.example.com, because IDNA2008 reserves labels with -- as their third and fourth characters.

isDate and isDateTime check that the day is in the month, including February 29 in a leap year:

TypeScript
isDate("2024-02-29"); // true
isDate("2023-02-29"); // false

A second of 60 is a leap second. isDateTime accepts it only at the end of a day that had a leap second, at 23:59:60 UTC. isTime has no date to check, so it never accepts a leap second:

TypeScript
isDateTime("2016-12-31T23:59:60Z"); // true
isDateTime("2017-12-31T23:59:60Z"); // false
isTime("23:59:60Z"); // false

RFC 3339 allows a lowercase t and z, so isDateTime accepts 2024-03-10t09:30:00z. A duration’s letters have to be uppercase, so isDuration rejects p1d.

isDateTimeExt checks an RFC 9557 date-time-ext, which is a date-time that can have a time zone and tags after it. It isn’t a JSON Schema format. JSON Schema’s date-time is isDateTime, which rejects a time zone:

TypeScript
isDateTime("2024-03-10T09:30:00-05:00[America/New_York]"); // false
isDateTimeExt("2024-03-10T09:30:00-05:00[America/New_York]"); // true

isDateTimeExt checks the syntax only. It doesn’t check that a time zone name is in the IANA Time Zone Database, or that the offset is right for the time zone.

Added in v1.2.0

The package also has functions for some of the formats in the JSON Schema Format Registry and the OpenAPI Format Registry, which list formats that other specifications define. They’re the ones that say exactly what’s valid. The tables say which registry each one is in. These are for strings:

Format Function Registry Specification
date-time-local isDateTimeLocal OpenAPI RFC 3339 full-date "T" partial-time
time-local isTimeLocal OpenAPI RFC 3339 partial-time
ipv4-cidr isIPv4Cidr OpenAPI An ipv4 address and a prefix length, in RFC 4632’s notation
ipv6-cidr isIPv6Cidr OpenAPI An ipv6 address and a prefix length, in RFC 4291’s notation
language isLanguageTag OpenAPI RFC 5646 Language-Tag
http-date isHttpDate Both RFC 9110 HTTP-date
media-range isMediaRange Both RFC 9110 media-range
sf-binary isSfBinary Both RFC 9651 sf-binary
sf-boolean isSfBoolean Both RFC 9651 sf-boolean
sf-string isSfString Both RFC 9651 sf-string
sf-token isSfToken Both RFC 9651 sf-token

These are for numbers, and take a number. Check that a value is a number before you call one:

TypeScript
const validateInt32 = (value: unknown) =>
typeof value !== "number" || isInt32(value);
Format Function Registry Valid values
int8 isInt8 Both Integers from -128 to 127
int16 isInt16 Both Integers from -32,768 to 32,767
int32 isInt32 Both Integers from -2,147,483,648 to 2,147,483,647
uint8 isUint8 Both Integers from 0 to 255
uint16 isUint16 OpenAPI Integers from 0 to 65,535
uint32 isUint32 OpenAPI Integers from 0 to 4,294,967,295
double-int isDoubleInt Both Integers from -(2^53 - 1) to 2^53 - 1, which a double stores without losing precision
sf-integer isSfInteger Both RFC 9651 integers, from -999,999,999,999,999 to 999,999,999,999,999
sf-decimal isSfDecimal Both RFC 9651 decimals, with at most 12 digits before the point and 3 after it

A number format checks the number that parsing the JSON gave, so a number is only as precise as a double. Every valid value is checked right, but a JSON number with more digits than a double can hold is checked as the double it became: 127.00000000000000001 is 127, which is a valid int8. An sf-decimal counts the digits of the shortest decimal that’s the number, so 1.230 has 2 digits after the point, and 0.1 + 0.2, which is 0.30000000000000004, has 17.

The OpenAPI registry names RFC 7231 for http-date. RFC 9110 replaced it, with the same grammar, and it’s the one the JSON Schema registry names.

isDateTimeLocal and isTimeLocal are like isDateTime and isTime without an offset. A leap second is at 23:59:60 UTC, and a time without an offset can’t be put in UTC, so they never accept one.

isIPv4Cidr and isIPv6Cidr take an address, /, and a prefix length, like 10.0.0.0/8 or 2001:db8::/32. The address can have bits set after the prefix, like 10.0.0.1/8, which is how RFC 4291 writes an address with the prefix of its network. The prefix length can’t have a leading zero, like the octets of an IPv4 address.

isLanguageTag checks that a language tag is well-formed: that it matches RFC 5646’s grammar, in any case. A well-formed tag isn’t always valid. It doesn’t check the subtags against the IANA Language Subtag Registry, so xx-YY is well-formed, and a tag can repeat a variant, like de-DE-1901-1901.

TypeScript
isLanguageTag("zh-Hant-TW"); // true
isLanguageTag("en_US"); // false

isHttpDate checks more than the grammar:

  • The day has to be in its month.
  • The day name has to be the date’s. RFC 9110 gives the parts of a date the meaning they have in RFC 5322, which says so.
  • A second of 60 has to be at the end of a day that had a leap second.
TypeScript
isHttpDate("Sun, 06 Nov 1994 08:49:37 GMT"); // true
isHttpDate("Mon, 06 Nov 1994 08:49:37 GMT"); // false

An HTTP date can also be in two obsolete forms, which isHttpDate accepts: Sunday, 06-Nov-94 08:49:37 GMT and Sun Nov 6 08:49:37 1994. The first one’s year has only two digits, so the century isn’t known. isHttpDate checks only what doesn’t need the century. February 29 has to be in a year that’s a leap year in some century, and a leap second has to be at 23:59:60. The day name isn’t checked.

The names of days and months are case-sensitive, as RFC 9110 says, so isHttpDate rejects sun, 06 Nov 1994 08:49:37 GMT.

The registries name RFC 8941 for the sf- formats. RFC 9651 replaced it, and the functions follow RFC 9651. The only difference is in isSfBinary: RFC 9651 allows = only as padding at the end of the base64, and RFC 8941’s grammar allows it anywhere, so isSfBinary rejects :a=b:.

The package doesn’t support the registries’ formats that don’t say exactly what’s valid: char, decimal, float, double, decimal128, int64, uint64, unixtime, binary, and html. For example, the registries define a char only as “a single character” with no definition of a character, and the OpenAPI registry says that decimal is “used in a variety of conflicting ways and is not interoperable.” It doesn’t support password or commonmark either, since every string is valid for them, or byte and base64url, which the registries deprecate.

An email address’s domain can be an address literal in brackets, like ada@[192.0.2.1] or ada@[IPv6:2001:db8::1]. RFC 5321 allows other kinds of address literal too, which start with a tag that names the kind, like ada@[x-example:abc]. IANA registers the tags, and IPv6 is the only one in its registry, so isEmail can’t know whether another kind is valid. It throws an Error for a tag other than IPv6. isIdnEmail does the same.

isIdnEmail checks the domain as an internationalized hostname, like isIdn does.

isRegex returns whether JavaScript can compile a string as a regular expression with the u flag. JSON Schema says that a regular expression uses ECMA-262’s syntax, and the u flag makes the syntax strict, so that a typo like \a isn’t valid.