Skip to content

Commit 775b578

Browse files
gregsdennisgregsdennis
authoredApr 19, 2025··
Merge pull request #1574 from json-schema-org/gregsdennis/format-registry
Gregsdennis/format registry
2 parents 8af8969 + ae1edc7 commit 775b578

File tree

2 files changed

+395
-10
lines changed

2 files changed

+395
-10
lines changed
 

‎specs/jsonschema-validation.md

+20-10
Original file line numberDiff line numberDiff line change
@@ -325,30 +325,40 @@ from previous iterations of this specification. Previously, `format` was an
325325
annotation-only keyword by default and implementations that supported assertion
326326
were required to offer some configuration that allowed users to explicitly
327327
enable assertion. Assertion is now a requirement in order to meet user
328-
expectations. See [json-schema-org/json-schema-spec
329-
#1520](https://github.com/json-schema-org/json-schema-spec/issues/1520) for
330-
more.
328+
expectations. See
329+
[json-schema-org/json-schema-spec #1520](https://github.com/json-schema-org/json-schema-spec/issues/1520)
330+
for more.
331331

332332
In addition to the assertion behavior, this keyword also produces its value as
333333
an annotation.
334334

335335
Implementations:
336336

337-
- SHOULD provide validation for each format attribute defined in this
338-
document;
339-
- MAY support format values not defined in this document, but such support MUST
340-
be configurable and disabled by default;
337+
- SHOULD provide validation for each format attribute defined in this document;
338+
- are encouraged to provide validation for format attributes listed in the
339+
{{format-registry}};
340+
- MAY support format values not defined in this document or listed in the
341+
registry, but such support MUST be configurable and disabled by default;
341342
- SHOULD use a common parsing library or a well-known regular expression for
342343
each format;
343-
- SHOULD clearly document how and to what degree each format attribute is
344-
validated.
344+
- SHOULD clearly document any limitations regarding format validation.
345345

346346
The requirement for validation of format values in general is limited to
347347
syntactic checking; implementations SHOULD NOT attempt to send an email, connect
348348
to a URL, or otherwise check the existence of an entity identified by a format
349349
instance.
350350

351-
#### Custom format values
351+
#### Format Registry {#format-registry}
352+
353+
In addition to the formats defined by this document, JSON Schema also maintains
354+
a registry of formats defined by other specifications and organizations. As of
355+
the publication of this document, the format registry can be found at
356+
<https://github.com/json-schema-org/json-schema-spec/blob/main/specs/registries/format.json>.
357+
358+
Implementations SHOULD support the formats listed in this registry as if they
359+
were defined by this document.
360+
361+
#### Custom `format` Values
352362

353363
Implementations MAY support custom format values. Save for agreement between
354364
parties, schema authors SHALL NOT expect a peer implementation to support such

‎specs/registries/format.json

+375
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
{
2+
"base64url": {
3+
"description": "Binary data encoded as a url-safe string as defined in RFC4648",
4+
"types": ["string"],
5+
"examples": ["U3dhZ2dlciByb2Nrcw"],
6+
"deprecated": true,
7+
"supportedBy": []
8+
},
9+
"binary": {
10+
"description": "Any sequence of octets",
11+
"definingBody": "OpenAPI",
12+
"definition": "https://spec.openapis.org/oas/v3.0.3.html#data-types",
13+
"types": ["string"],
14+
"examples": ["binary data"],
15+
"deprecated": true,
16+
"supportedBy": []
17+
},
18+
"byte": {
19+
"description": "Base64 encoded data as defined in RFC4648",
20+
"definingBody": "OpenAPI",
21+
"definition": "https://spec.openapis.org/oas/v3.0.3.html#data-types",
22+
"types": ["string"],
23+
"examples": ["U3dhZ2dlciByb2Nrcw=="],
24+
"deprecated": true,
25+
"supportedBy": []
26+
},
27+
"char": {
28+
"description": "A single character",
29+
"types": ["string"],
30+
"examples": ["a"],
31+
"deprecated": false,
32+
"supportedBy": []
33+
},
34+
"commonmark": {
35+
"description": "Commonmark-formatted text",
36+
"definingBody": "OpenAPI",
37+
"definition": "https://spec.openapis.org/oas/latest.html#data-types",
38+
"types": ["string"],
39+
"examples": ["# Heading\n\nSome **bold** text."],
40+
"deprecated": false,
41+
"supportedBy": []
42+
},
43+
"date": {
44+
"description": "Date as defined by full-date - RFC3339",
45+
"definingBody": "JSON Schema",
46+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-dates-times-and-duration",
47+
"types": ["string"],
48+
"examples": ["2017-07-21"],
49+
"deprecated": false,
50+
"supportedBy": []
51+
},
52+
"date-time": {
53+
"description": "Date and time as defined by date-time - RFC3339",
54+
"definingBody": "JSON Schema",
55+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-dates-times-and-duration",
56+
"types": ["string"],
57+
"examples": ["2017-07-21T17:32:28Z"],
58+
"deprecated": false,
59+
"supportedBy": []
60+
},
61+
"decimal": {
62+
"description": "A fixed point decimal number of unspecified precision and range",
63+
"types": ["string", "number"],
64+
"examples": ["123.45"],
65+
"deprecated": false,
66+
"supportedBy": []
67+
},
68+
"decimal128": {
69+
"description": "A decimal floating-point number with 34 significant decimal digits",
70+
"types": ["string", "number"],
71+
"examples": ["123.4567890123456789012345678901234"],
72+
"deprecated": false,
73+
"supportedBy": []
74+
},
75+
"double": {
76+
"description": "Double precision floating point number",
77+
"definingBody": "OpenAPI",
78+
"definition": "https://spec.openapis.org/oas/latest.html#data-types",
79+
"types": ["number"],
80+
"examples": [-1.7976931348623157e+308, -1, -4.9406564584124654e-324, 0, 4.9406564584124654e-324, 1, 1.7976931348623157e+308],
81+
"deprecated": false,
82+
"supportedBy": []
83+
},
84+
"double-int": {
85+
"description": "An integer that can be stored in an IEEE 754 double-precision number without loss of precision",
86+
"types": ["number"],
87+
"examples": [9007199254740991],
88+
"deprecated": false,
89+
"supportedBy": []
90+
},
91+
"duration": {
92+
"description": "Duration as defined by duration - RFC3339",
93+
"definingBody": "JSON Schema",
94+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-dates-times-and-duration",
95+
"types": ["string"],
96+
"examples": ["P3Y6M4DT12H30M5S"],
97+
"deprecated": false,
98+
"supportedBy": []
99+
},
100+
"email": {
101+
"description": "An email address as defined as Mailbox in RFC5321",
102+
"definingBody": "JSON Schema",
103+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-email-addresses",
104+
"types": ["string"],
105+
"examples": ["user@example.com"],
106+
"deprecated": false,
107+
"supportedBy": []
108+
},
109+
"float": {
110+
"description": "Single precision floating point number",
111+
"definingBody": "OpenAPI",
112+
"definition": "https://spec.openapis.org/oas/latest.html#data-types",
113+
"types": ["number"],
114+
"examples": [-3.40282347e+38, -1, -1.17549435e-38, 0, 1.17549435e-38, 1, 3.40282347e+38],
115+
"deprecated": false,
116+
"supportedBy": []
117+
},
118+
"hostname": {
119+
"description": "A host name as defined by RFC1123",
120+
"definingBody": "JSON Schema",
121+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-hostnames",
122+
"types": ["string"],
123+
"examples": ["example.com"],
124+
"deprecated": false,
125+
"supportedBy": []
126+
},
127+
"html": {
128+
"description": "HTML-formatted text",
129+
"definingBody": "OpenAPI",
130+
"definition": "https://spec.openapis.org/oas/latest.html#data-types",
131+
"types": ["string"],
132+
"examples": ["<p>This is a paragraph.</p>"],
133+
"deprecated": false,
134+
"supportedBy": []
135+
},
136+
"http-date": {
137+
"description": "Date and time as defined by HTTP-date - RFC7231",
138+
"types": ["string"],
139+
"examples": ["Sun, 06 Nov 1994 08:49:37 GMT"],
140+
"deprecated": false,
141+
"supportedBy": []
142+
},
143+
"idn-email": {
144+
"description": "An email address as defined as Mailbox in RFC6531",
145+
"definingBody": "JSON Schema",
146+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-email-addresses",
147+
"types": ["string"],
148+
"examples": ["user@exämple.com"],
149+
"deprecated": false,
150+
"supportedBy": []
151+
},
152+
"idn-hostname": {
153+
"description": "An internationalized host name as defined by RFC5890",
154+
"definingBody": "JSON Schema",
155+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-hostnames",
156+
"types": ["string"],
157+
"examples": ["exämple.com"],
158+
"deprecated": false,
159+
"supportedBy": []
160+
},
161+
"int16": {
162+
"description": "Signed 16-bit integer",
163+
"types": ["number"],
164+
"examples": [-32768, -1, 0, 1, 32767],
165+
"deprecated": false,
166+
"supportedBy": []
167+
},
168+
"int32": {
169+
"description": "Signed 32-bit integer",
170+
"definingBody": "OpenAPI",
171+
"definition": "https://spec.openapis.org/oas/v3.1.1.html#data-type-format",
172+
"types": ["number"],
173+
"examples": [-2147483648, -1, 0, 1, 2147483647],
174+
"deprecated": false,
175+
"supportedBy": []
176+
},
177+
"int64": {
178+
"description": "Signed 64-bit integer",
179+
"definingBody": "OpenAPI",
180+
"definition": "https://spec.openapis.org/oas/v3.1.1.html#data-type-format",
181+
"types": ["number"],
182+
"examples": [-9223372036854775808, -1, 0, 1, 9223372036854775807],
183+
"deprecated": false,
184+
"supportedBy": []
185+
},
186+
"int8": {
187+
"description": "Signed 8-bit integer",
188+
"definingBody": "OpenAPI",
189+
"definition": "https://spec.openapis.org/oas/latest.html#data-types",
190+
"types": ["number"],
191+
"examples": [-128, -1, 0, 1, 127],
192+
"deprecated": false,
193+
"supportedBy": []
194+
},
195+
"ipv4": {
196+
"description": "An IPv4 address as defined as dotted-quad by RFC2673",
197+
"definingBody": "JSON Schema",
198+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-ip-addresses",
199+
"types": ["string"],
200+
"examples": ["192.168.0.1"],
201+
"deprecated": false,
202+
"supportedBy": []
203+
},
204+
"ipv6": {
205+
"description": "An IPv6 address as defined by RFC4673",
206+
"definingBody": "JSON Schema",
207+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-ip-addresses",
208+
"types": ["string"],
209+
"examples": ["2001:0db8:85a3:0000:0000:8a2e:0370:7334"],
210+
"deprecated": false,
211+
"supportedBy": []
212+
},
213+
"iri": {
214+
"description": "An Internationalized Resource Identifier as defined in RFC3987",
215+
"definingBody": "JSON Schema",
216+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-resource-identifiers",
217+
"types": ["string"],
218+
"examples": ["https://example.com/rosé"],
219+
"deprecated": false,
220+
"supportedBy": []
221+
},
222+
"iri-reference": {
223+
"description": "An Internationalized Resource Identifier as defined in RFC3987",
224+
"definingBody": "JSON Schema",
225+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-resource-identifiers",
226+
"types": ["string"],
227+
"examples": ["../resource.json"],
228+
"deprecated": false,
229+
"supportedBy": []
230+
},
231+
"json-pointer": {
232+
"description": "A JSON string representation of a JSON Pointer as defined in RFC6901",
233+
"definingBody": "JSON Schema",
234+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-json-pointers",
235+
"types": ["string"],
236+
"examples": ["/foo/bar"],
237+
"deprecated": false,
238+
"supportedBy": []
239+
},
240+
"media-range": {
241+
"description": "A media type as defined by the media-range ABNF production in RFC9110.",
242+
"definingBody": "OpenAPI",
243+
"definition": "https://www.rfc-editor.org/rfc/rfc9110#field.accept",
244+
"types": ["string"],
245+
"examples": ["text/html"],
246+
"deprecated": false,
247+
"supportedBy": []
248+
},
249+
"regex": {
250+
"description": "A regular expression as defined in ECMA-262",
251+
"definingBody": "JSON Schema",
252+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-regex",
253+
"types": ["string"],
254+
"examples": ["^[a-zA-Z0-9]+$"],
255+
"deprecated": false,
256+
"supportedBy": []
257+
},
258+
"relative-json-pointer": {
259+
"description": "A JSON string representation of a relative JSON Pointer as defined in draft RFC 01",
260+
"definingBody": "JSON Schema",
261+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-json-pointers",
262+
"types": ["string"],
263+
"examples": ["1/0"],
264+
"deprecated": false,
265+
"supportedBy": []
266+
},
267+
"sf-binary": {
268+
"description": "Structured fields byte sequence as defined in RFC8941",
269+
"definingBody": "RFC 8941",
270+
"definition": "https://www.rfc-editor.org/rfc/rfc8941#name-byte-sequences",
271+
"types": ["string"],
272+
"examples": ["U3dhZ2dlciByb2Nrcw=="],
273+
"deprecated": false,
274+
"supportedBy": []
275+
},
276+
"sf-boolean": {
277+
"description": "Structured fields boolean as defined in RFC8941",
278+
"definingBody": "RFC 8941",
279+
"definition": "https://www.rfc-editor.org/rfc/rfc8941#name-booleans",
280+
"types": ["string"],
281+
"examples": ["true", "false"],
282+
"deprecated": false,
283+
"supportedBy": []
284+
},
285+
"sf-decimal": {
286+
"description": "Structured fields decimal as defined in RFC8941",
287+
"definingBody": "RFC 8941",
288+
"definition": "https://www.rfc-editor.org/rfc/rfc8941#name-decimals",
289+
"types": ["number"],
290+
"examples": ["123.45"],
291+
"deprecated": false,
292+
"supportedBy": []
293+
},
294+
"sf-integer": {
295+
"description": "Structured fields integer as defined in RFC8941",
296+
"definingBody": "RFC 8941",
297+
"definition": "https://www.rfc-editor.org/rfc/rfc8941#name-integers",
298+
"types": ["number"],
299+
"examples": [123],
300+
"deprecated": false,
301+
"supportedBy": []
302+
},
303+
"sf-string": {
304+
"description": "Structured fields string as defined in RFC8941",
305+
"definingBody": "RFC 8941",
306+
"definition": "https://www.rfc-editor.org/rfc/rfc8941#name-strings",
307+
"types": ["string"],
308+
"examples": ["example"],
309+
"deprecated": false,
310+
"supportedBy": []
311+
},
312+
"sf-token": {
313+
"description": "Structured fields token as defined in RFC8941",
314+
"definingBody": "RFC 8941",
315+
"definition": "https://www.rfc-editor.org/rfc/rfc8941#name-tokens",
316+
"types": ["string"],
317+
"examples": ["token"],
318+
"deprecated": false,
319+
"supportedBy": []
320+
},
321+
"time": {
322+
"description": "Time as defined by full-time - RFC3339",
323+
"definingBody": "JSON Schema",
324+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-dates-times-and-duration",
325+
"types": ["string"],
326+
"examples": ["13:45:30Z", "13:45:30+01:00"],
327+
"deprecated": false,
328+
"supportedBy": []
329+
},
330+
"uint8": {
331+
"description": "Unsigned 8-bit integer",
332+
"definingBody": "OpenAPI",
333+
"definition": "https://spec.openapis.org/oas/latest.html#data-types",
334+
"types": ["number"],
335+
"examples": [0, 1, 255],
336+
"deprecated": false,
337+
"supportedBy": []
338+
},
339+
"uri": {
340+
"description": "A Uniform Resource Identifier as defined in RFC3986",
341+
"definingBody": "JSON Schema",
342+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-resource-identifiers",
343+
"types": ["string"],
344+
"examples": ["https://example.com"],
345+
"deprecated": false,
346+
"supportedBy": []
347+
},
348+
"uri-reference": {
349+
"description": "A URI reference as defined in RFC3986",
350+
"definingBody": "JSON Schema",
351+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-resource-identifiers",
352+
"types": ["string"],
353+
"examples": ["../resource.json"],
354+
"deprecated": false,
355+
"supportedBy": []
356+
},
357+
"uri-template": {
358+
"description": "A URI Template as defined in RFC6570",
359+
"definingBody": "JSON Schema",
360+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-uri-template",
361+
"types": ["string"],
362+
"examples": ["https://example.com/{id}"],
363+
"deprecated": false,
364+
"supportedBy": []
365+
},
366+
"uuid": {
367+
"description": "A Universally Unique IDentifier as defined in RFC4122",
368+
"definingBody": "JSON Schema",
369+
"definition": "https://json-schema.org/draft/2020-12/json-schema-validation.html#name-resource-identifiers",
370+
"types": ["string"],
371+
"examples": ["f81d4fae-7dec-11d0-a765-00a0c91e6bf6"],
372+
"deprecated": false,
373+
"supportedBy": []
374+
}
375+
}

0 commit comments

Comments
 (0)
Please sign in to comment.