Validate formats
Each format has an is function, which returns whether a value is valid
for the format:
import { isEmail, isIPv4 } from "@hyperjump/json-schema-formats";
isIPv4("256.0.0.1"); // falseJSON Schema’s formats apply only to strings, so their functions take only strings. Check that a value is a string before you call one:
const validateEmail = (value: unknown) => typeof value !== "string" || isEmail(value);Functions
Section titled “Functions”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.
Formats that changed
Section titled “Formats that changed”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.
Dates and times
Section titled “Dates and times”isDate and isDateTime check that the day is in the month, including
February 29 in a leap year:
isDate("2024-02-29"); // trueisDate("2023-02-29"); // falseA 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:
isDateTime("2016-12-31T23:59:60Z"); // trueisDateTime("2017-12-31T23:59:60Z"); // falseisTime("23:59:60Z"); // falseRFC 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.
Time zones
Section titled “Time zones”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:
isDateTime("2024-03-10T09:30:00-05:00[America/New_York]"); // falseisDateTimeExt("2024-03-10T09:30:00-05:00[America/New_York]"); // trueisDateTimeExt 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.
Registry formats
Section titled “Registry formats”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:
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.
isLanguageTag("zh-Hant-TW"); // trueisLanguageTag("en_US"); // falseisHttpDate 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
60has to be at the end of a day that had a leap second.
isHttpDate("Sun, 06 Nov 1994 08:49:37 GMT"); // trueisHttpDate("Mon, 06 Nov 1994 08:49:37 GMT"); // falseAn 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.
The email and idn-email formats
Section titled “The email and idn-email formats”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.
Regular expressions
Section titled “Regular expressions”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.