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
What each format is

Each predicate is the grammar of the RFC the specification names, applied to the whole string:

  • date-time, date and time are RFC 3339 §5.6: T and Z in 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.
  • duration is RFC 3339 Appendix A as written: units in order, none skipped (P1Y1D is invalid, since a year may be followed only by a month), a T before any hour, minute or second and at least one after it, and weeks alone.
  • email is RFC 5321's Mailbox: a dot-string or a quoted string of at most 64 octets, then a domain of at most 255 that is a hostname or an address literal ([127.0.0.1], [IPv6:::1], or a tag and its content).
  • hostname is 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.
  • ipv4 is RFC 2673's dotted quad: four decimal parts of 0 to 255, with no leading zero. ipv6 is 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.
  • uuid is RFC 4122's 8-4-4-4-12 hex digits, in either case, of any version or variant.
  • uri and uri-reference are RFC 3986 §3 and §4.1; iri and iri-reference are RFC 3987 §2.2, the same grammar with any ucschar where an unreserved character goes and iprivate in the query.
  • uri-template is RFC 6570 §2, any level.
  • regex is a pattern nish/regex compiles (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
sstringrequired

the text to check, whole: nothing before or after the date is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the date-time is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the duration is allowed.

returnsboolean

true when s is a duration, false otherwise.

isEmail

Whether s is an RFC 5321 mailbox, joe.bloggs@example.com.

const isEmail: (s: string) => boolean
sstringrequired

the text to check, whole: nothing before or after the mailbox is allowed.

returnsboolean

true when s is a mailbox, false otherwise.

isHostname

Whether s is a host name, www.example.com.

const isHostname: (s: string) => boolean
sstringrequired

the text to check, whole: nothing before or after the host name is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the IPv4 address is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the IPv6 address is allowed.

returnsboolean

true when s is an IPv6 address, false otherwise.

isIri

Whether s is an absolute IRI, http://ƒøø.ßår/?∂éœ=πîx.

const isIri: (s: string) => boolean
sstringrequired

the text to check, whole: nothing before or after the IRI is allowed.

returnsboolean

true when s is an IRI, false otherwise.

isIriReference

Whether s is an IRI or a relative IRI reference.

const isIriReference: (s: string) => boolean
sstringrequired

the text to check, whole: nothing before or after the IRI reference is allowed.

returnsboolean

true 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
sstringrequired

the pattern source, without slashes or flags.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the time is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the URI is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the URI reference is allowed.

returnsboolean

true 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
sstringrequired

the text to check, whole: nothing before or after the URI template is allowed.

returnsboolean

true when s is a URI template, false otherwise.

isUuid

Whether s is a UUID, 2eb8aa08-aa98-11ea-b4aa-73b441d16380.

const isUuid: (s: string) => boolean
sstringrequired

the text to check, whole: nothing before or after the UUID is allowed.

returnsboolean

true 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
idi32required

a format id from jsonFormatId.

valuestringrequired

the string instance to check.

returnsi32

JSON_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
namestringrequired

the name a schema's format keyword gives.

valuestringrequired

the string instance to check.

returnsi32

JSON_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.