nish/json-format
The string formats of JSON Schema draft 2020-12 (§7.3 of the validation vocabulary), each a predicate, and one dispatcher that answers valid, invalid or unknown for a format named in a schema.
import {
JSON_FORMAT_DATE,
JSON_FORMAT_DATE_TIME,
JSON_FORMAT_DURATION,
JSON_FORMAT_EMAIL,
JSON_FORMAT_HOSTNAME,
JSON_FORMAT_INVALID,
JSON_FORMAT_IPV4,
JSON_FORMAT_IPV6,
JSON_FORMAT_IRI,
JSON_FORMAT_IRI_REFERENCE,
JSON_FORMAT_REGEX,
JSON_FORMAT_TIME,
JSON_FORMAT_UNKNOWN,
JSON_FORMAT_URI,
JSON_FORMAT_URI_REFERENCE,
JSON_FORMAT_URI_TEMPLATE,
JSON_FORMAT_UUID,
JSON_FORMAT_VALID,
isDate,
isDateTime,
isDuration,
isEmail,
isHostname,
isIpv4,
isIpv6,
isIri,
isIriReference,
isRegex,
isTime,
isUri,
isUriReference,
isUriTemplate,
isUuid,
jsonFormatCheck,
jsonFormatId,
jsonFormatValidate,
} from "nish/json-format";
import { jsonFormatId, jsonFormatCheck, isEmail, JSON_FORMAT_VALID } from "nish/json-format"
isEmail("joe.bloggs@example.com") // true
const id = jsonFormatId("date-time") // resolve the name once, when the schema is read
jsonFormatCheck(id, "1963-06-19T08:30:06Z") // JSON_FORMAT_VALID, for each instance
jsonFormatValidate("idn-email", "x@y") // JSON_FORMAT_UNKNOWN: not checked here
isDate
Whether s is an RFC 3339 full-date, 1963-06-19.
isDateTime
Whether s is an RFC 3339 date-time, 1963-06-19T08:30:06.283185Z.
isDuration
Whether s is an RFC 3339 Appendix A duration, P3Y6M4DT12H30M5S.
isEmail
Whether s is an RFC 5321 mailbox, joe.bloggs@example.com.
isHostname
Whether s is a host name, www.example.com.
isIpv4
Whether s is a dotted-quad IPv4 address, 192.168.0.1.
isIpv6
Whether s is an IPv6 address, ::ffff:192.168.0.1.
isIri
Whether s is an absolute IRI, http://ƒøø.ßår/?∂éœ=πîx.
isIriReference
Whether s is an IRI or a relative IRI reference.
isRegex
Whether s is a regular expression nish/regex compiles with no flags.
isTime
Whether s is an RFC 3339 full-time, 08:30:06Z or 08:30:06+01:00.
isUri
Whether s is an absolute URI, http://example.com/a?b#c.
isUriReference
Whether s is a URI or a relative reference, ../a?b#c.
isUriTemplate
Whether s is an RFC 6570 URI template, http://example.com/{term:1}/{term}.
isUuid
Whether s is a UUID, 2eb8aa08-aa98-11ea-b4aa-73b441d16380.
jsonFormatCheck
value checked against the format id from jsonFormatId: JSON_FORMAT_VALID or JSON_FORMAT_INVALID, or JSON_FORMAT_UNKNOWN for an id that names no format, -1 included.
jsonFormatId
The id of the format name for jsonFormatCheck, one of the JSON_FORMAT_* ids, or -1 for a format this module does not check.
jsonFormatValidate
value checked against the format named name: JSON_FORMAT_VALID, JSON_FORMAT_INVALID, or JSON_FORMAT_UNKNOWN for a format this module does not check.
What each format is
Each predicate is the grammar of the RFC the specification names, applied to the whole string:
-
date-time,dateandtimeare RFC 3339 §5.6:TandZin either case, a fraction of any length, an offset of at most 23:59, the month's length in the year's calendar, and a second of 60 only where the time is 23:59 in UTC once the offset is taken off. -
durationis RFC 3339 Appendix A as written: units in order, none skipped (P1Y1Dis invalid, since a year may be followed only by a month), aTbefore any hour, minute or second and at least one after it, and weeks alone. -
emailis RFC 5321'sMailbox: a dot-string or a quoted string of at most 64 octets, then a domain of at most 255 that is ahostnameor an address literal ([127.0.0.1],[IPv6:::1], or a tag and its content). -
hostnameis RFC 1123: labels of 1 to 63 letters, digits and hyphens with no hyphen at either end, 253 octets in all, and no trailing dot. An A-label (xn--) is checked as letters and digits; its Punycode is not decoded. -
ipv4is RFC 2673's dotted quad: four decimal parts of 0 to 255, with no leading zero.ipv6is RFC 4291 §2.2: at most one::, groups of 1 to 4 hex digits, an IPv4 tail counted as two, and no zone or prefix length. -
uuidis RFC 4122's 8-4-4-4-12 hex digits, in either case, of any version or variant. -
urianduri-referenceare RFC 3986 §3 and §4.1;iriandiri-referenceare RFC 3987 §2.2, the same grammar with anyucscharwhere an unreserved character goes andiprivatein the query. uri-templateis RFC 6570 §2, any level.regexis a patternnish/regexcompiles (see "What is not checked").
Why the URI grammar is checked here and not by `nish/net/url`
urlParse reads an absolute URL a client is about to fetch, and refuses
what two readers could take for different hosts: a percent-encoded host
byte, a numeric host that is not a dotted-decimal IPv4 address, an
IPvFuture literal, a port above 65535, any byte past ASCII, and a reference
with no scheme (std/net/url.ts). Each of those is a valid RFC 3986 URI,
IRI or relative reference, which this module must answer valid. It also
allocates the parts it answers. So this module walks the ABNF itself, over
the string, allocating nothing.
What is not checked
jsonFormatId answers -1, and the dispatcher
JSON_FORMAT_UNKNOWN, for idn-email, idn-hostname, json-pointer,
relative-json-pointer and any other name: an unknown format is an
annotation, which a validator accepts (§7.2.3). regex is answered by
regexCompile, which is stricter than ECMA-262: it refuses lookaround and
backreferences, which it does not implement, and reads the pattern with the
u flag's rules, so a lone { or ] is an error. Such a pattern is valid
ECMA-262 and is answered invalid here, a false negative.
What a call costs
Every check but regex is linear in the length of
its string: each unit is read a small fixed number of times (at most four, in
a URI's authority, which is found and then split at @ and :). It
allocates nothing and cannot panic. jsonFormatId compares the
name with up to 15 strings; resolve it once per schema, not per instance.
isRegex compiles the pattern, which allocates the program nish/regex
builds. That is not linear in the pattern's length, since a counted repeat
copies its body, but nish/regex's limits bound it: (a{1000}){100} is
refused at 100,000 instructions (REGEX_MAX_INSTRUCTIONS) or a 4 MiB slot
table, whichever comes first.
Offsets are code units: UTF-8 bytes natively and UTF-16 units under Node. The checks answer the same on both, since every non-ASCII character is decoded where a grammar allows one and refused everywhere else.
Functions
isDate
Whether s is an RFC 3339 full-date, 1963-06-19.
const isDate: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the date is allowed.
returnsbooleantrue when s is a date, false otherwise.
isDateTime
Whether s is an RFC 3339 date-time, 1963-06-19T08:30:06.283185Z.
const isDateTime: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the date-time is allowed.
returnsbooleantrue when s is a date-time, false otherwise.
isDuration
Whether s is an RFC 3339 Appendix A duration, P3Y6M4DT12H30M5S.
The ABNF lets each unit be followed only by the next one (dur-year = 1*DIGIT "Y" [dur-month]), so the units of each half must be consecutive
in YMD and HMS order: P1Y1D and PT1H1S are invalid as written,
though ISO 8601 allows them.
const isDuration: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the duration is allowed.
returnsbooleantrue when s is a duration, false otherwise.
isEmail
Whether s is an RFC 5321 mailbox, joe.bloggs@example.com.
const isEmail: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the mailbox is allowed.
returnsbooleantrue when s is a mailbox, false otherwise.
isHostname
Whether s is a host name, www.example.com.
const isHostname: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the host name is allowed.
returnsbooleantrue when s is a host name, false otherwise.
isIpv4
Whether s is a dotted-quad IPv4 address, 192.168.0.1.
const isIpv4: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the IPv4 address is allowed.
returnsbooleantrue when s is an IPv4 address, false otherwise.
isIpv6
Whether s is an IPv6 address, ::ffff:192.168.0.1.
const isIpv6: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the IPv6 address is allowed.
returnsbooleantrue when s is an IPv6 address, false otherwise.
isIri
Whether s is an absolute IRI, http://ƒøø.ßår/?∂éœ=πîx.
const isIri: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the IRI is allowed.
returnsbooleantrue when s is an IRI, false otherwise.
isIriReference
Whether s is an IRI or a relative IRI reference.
const isIriReference: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the IRI reference is allowed.
returnsbooleantrue when s is an IRI reference, false otherwise.
isRegex
Whether s is a regular expression nish/regex compiles with no flags.
Lookaround, backreferences and what the u flag refuses are answered
false, though ECMA-262 accepts them (see the module header).
const isRegex: (s: string) => boolean
sstringrequiredthe pattern source, without slashes or flags.
returnsbooleantrue when nish/regex compiles s, false otherwise.
isTime
Whether s is an RFC 3339 full-time, 08:30:06Z or 08:30:06+01:00.
const isTime: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the time is allowed.
returnsbooleantrue when s is a time, false otherwise.
isUri
Whether s is an absolute URI, http://example.com/a?b#c.
const isUri: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the URI is allowed.
returnsbooleantrue when s is a URI, false otherwise.
isUriReference
Whether s is a URI or a relative reference, ../a?b#c.
const isUriReference: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the URI reference is allowed.
returnsbooleantrue when s is a URI reference, false otherwise.
isUriTemplate
Whether s is an RFC 6570 URI template,
http://example.com/{term:1}/{term}.
const isUriTemplate: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the URI template is allowed.
returnsbooleantrue when s is a URI template, false otherwise.
isUuid
Whether s is a UUID, 2eb8aa08-aa98-11ea-b4aa-73b441d16380.
const isUuid: (s: string) => boolean
sstringrequiredthe text to check, whole: nothing before or after the UUID is allowed.
returnsbooleantrue when s is a UUID, false otherwise.
jsonFormatCheck
value checked against the format id from jsonFormatId:
JSON_FORMAT_VALID or JSON_FORMAT_INVALID, or JSON_FORMAT_UNKNOWN
for an id that names no format, -1 included.
const jsonFormatCheck: (id: i32, value: string) => i32
idi32requireda format id from jsonFormatId.
valuestringrequiredthe string instance to check.
returnsi32JSON_FORMAT_VALID, JSON_FORMAT_INVALID or JSON_FORMAT_UNKNOWN.
jsonFormatId
The id of the format name for jsonFormatCheck, one of the
JSON_FORMAT_* ids, or -1 for a format this module does not check.
const jsonFormatId: (name: string) => i32
namestringrequired
the name a schema's format keyword gives, such as
"date-time".
returnsi32
the format's JSON_FORMAT_* id, or -1 when this module does not
check that format.
jsonFormatValidate
value checked against the format named name: JSON_FORMAT_VALID,
JSON_FORMAT_INVALID, or JSON_FORMAT_UNKNOWN for a format this module
does not check. A validator that checks many instances against one schema
resolves the name once with jsonFormatId and calls jsonFormatCheck.
const jsonFormatValidate: (
name: string,
value: string,
) => i32
namestringrequiredthe name a schema's format keyword gives.
valuestringrequiredthe string instance to check.
returnsi32JSON_FORMAT_VALID, JSON_FORMAT_INVALID or JSON_FORMAT_UNKNOWN.
Constants
1
JSON_FORMAT_DATE: i32
The id of date.
0
JSON_FORMAT_DATE_TIME: i32
The id of date-time, for jsonFormatCheck.
3
JSON_FORMAT_DURATION: i32
The id of duration.
4
JSON_FORMAT_EMAIL: i32
The id of email.
5
JSON_FORMAT_HOSTNAME: i32
The id of hostname.
0
JSON_FORMAT_INVALID: i32
The dispatcher's answer for a string the format refuses.
6
JSON_FORMAT_IPV4: i32
The id of ipv4.
7
JSON_FORMAT_IPV6: i32
The id of ipv6.
11
JSON_FORMAT_IRI: i32
The id of iri.
12
JSON_FORMAT_IRI_REFERENCE: i32
The id of iri-reference.
14
JSON_FORMAT_REGEX: i32
The id of regex.
2
JSON_FORMAT_TIME: i32
The id of time.
-1
JSON_FORMAT_UNKNOWN: i32
The dispatcher's answer for a format this module does not check.
9
JSON_FORMAT_URI: i32
The id of uri.
10
JSON_FORMAT_URI_REFERENCE: i32
The id of uri-reference.
13
JSON_FORMAT_URI_TEMPLATE: i32
The id of uri-template.
8
JSON_FORMAT_UUID: i32
The id of uuid.
1
JSON_FORMAT_VALID: i32
The dispatcher's answer for a string the format accepts.

