idnits 2.17.1 draft-bhutton-json-schema-validation-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (10 June 2022) is 683 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2673 (Obsoleted by RFC 6891) -- Obsolete informational reference (is this intentional?): RFC 4329 (Obsoleted by RFC 9239) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Wright, Ed. 3 Internet-Draft 4 Intended status: Informational H. Andrews, Ed. 5 Expires: 12 December 2022 6 B. Hutton, Ed. 7 Postman 8 10 June 2022 10 JSON Schema Validation: A Vocabulary for Structural Validation of JSON 11 draft-bhutton-json-schema-validation-01 13 Abstract 15 JSON Schema (application/schema+json) has several purposes, one of 16 which is JSON instance validation. This document specifies a 17 vocabulary for JSON Schema to describe the meaning of JSON documents, 18 provide hints for user interfaces working with JSON data, and to make 19 assertions about what a valid document must look like. 21 Note to Readers 23 The issues list for this draft can be found at https://github.com/ 24 json-schema-org/json-schema-spec/issues. 26 For additional information, see https://json-schema.org/. 28 To provide feedback, use this issue tracker, the communication 29 methods listed on the homepage, or email the document editors. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 12 December 2022. 48 Copyright Notice 50 Copyright (c) 2022 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. Code Components 58 extracted from this document must include Revised BSD License text as 59 described in Section 4.e of the Trust Legal Provisions and are 60 provided without warranty as described in the Revised BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4 66 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 4. Interoperability Considerations . . . . . . . . . . . . . . . 4 68 4.1. Validation of String Instances . . . . . . . . . . . . . 4 69 4.2. Validation of Numeric Instances . . . . . . . . . . . . . 5 70 4.3. Regular Expressions . . . . . . . . . . . . . . . . . . . 5 71 5. Meta-Schema . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 6. A Vocabulary for Structural Validation . . . . . . . . . . . 5 73 6.1. Validation Keywords for Any Instance Type . . . . . . . . 6 74 6.1.1. type . . . . . . . . . . . . . . . . . . . . . . . . 6 75 6.1.2. enum . . . . . . . . . . . . . . . . . . . . . . . . 6 76 6.1.3. const . . . . . . . . . . . . . . . . . . . . . . . . 6 77 6.2. Validation Keywords for Numeric Instances (number and 78 integer) . . . . . . . . . . . . . . . . . . . . . . . . 6 79 6.2.1. multipleOf . . . . . . . . . . . . . . . . . . . . . 6 80 6.2.2. maximum . . . . . . . . . . . . . . . . . . . . . . . 7 81 6.2.3. exclusiveMaximum . . . . . . . . . . . . . . . . . . 7 82 6.2.4. minimum . . . . . . . . . . . . . . . . . . . . . . . 7 83 6.2.5. exclusiveMinimum . . . . . . . . . . . . . . . . . . 7 84 6.3. Validation Keywords for Strings . . . . . . . . . . . . . 7 85 6.3.1. maxLength . . . . . . . . . . . . . . . . . . . . . . 7 86 6.3.2. minLength . . . . . . . . . . . . . . . . . . . . . . 8 87 6.3.3. pattern . . . . . . . . . . . . . . . . . . . . . . . 8 88 6.4. Validation Keywords for Arrays . . . . . . . . . . . . . 8 89 6.4.1. maxItems . . . . . . . . . . . . . . . . . . . . . . 8 90 6.4.2. minItems . . . . . . . . . . . . . . . . . . . . . . 8 91 6.4.3. uniqueItems . . . . . . . . . . . . . . . . . . . . . 8 92 6.4.4. maxContains . . . . . . . . . . . . . . . . . . . . . 9 93 6.4.5. minContains . . . . . . . . . . . . . . . . . . . . . 9 94 6.5. Validation Keywords for Objects . . . . . . . . . . . . . 9 95 6.5.1. maxProperties . . . . . . . . . . . . . . . . . . . . 9 96 6.5.2. minProperties . . . . . . . . . . . . . . . . . . . . 10 97 6.5.3. required . . . . . . . . . . . . . . . . . . . . . . 10 98 6.5.4. dependentRequired . . . . . . . . . . . . . . . . . . 10 99 7. Vocabularies for Semantic Content With "format" . . . . . . . 10 100 7.1. Foreword . . . . . . . . . . . . . . . . . . . . . . . . 10 101 7.2. Implementation Requirements . . . . . . . . . . . . . . . 11 102 7.2.1. Format-Annotation Vocabulary . . . . . . . . . . . . 11 103 7.2.2. Format-Assertion Vocabulary . . . . . . . . . . . . . 12 104 7.2.3. Custom format attributes . . . . . . . . . . . . . . 13 105 7.3. Defined Formats . . . . . . . . . . . . . . . . . . . . . 13 106 7.3.1. Dates, Times, and Duration . . . . . . . . . . . . . 14 107 7.3.2. Email Addresses . . . . . . . . . . . . . . . . . . . 14 108 7.3.3. Hostnames . . . . . . . . . . . . . . . . . . . . . . 15 109 7.3.4. IP Addresses . . . . . . . . . . . . . . . . . . . . 15 110 7.3.5. Resource Identifiers . . . . . . . . . . . . . . . . 15 111 7.3.6. uri-template . . . . . . . . . . . . . . . . . . . . 16 112 7.3.7. JSON Pointers . . . . . . . . . . . . . . . . . . . . 16 113 7.3.8. regex . . . . . . . . . . . . . . . . . . . . . . . . 17 114 8. A Vocabulary for the Contents of String-Encoded Data . . . . 17 115 8.1. Foreword . . . . . . . . . . . . . . . . . . . . . . . . 17 116 8.2. Implementation Requirements . . . . . . . . . . . . . . . 17 117 8.3. contentEncoding . . . . . . . . . . . . . . . . . . . . . 18 118 8.4. contentMediaType . . . . . . . . . . . . . . . . . . . . 19 119 8.5. contentSchema . . . . . . . . . . . . . . . . . . . . . . 19 120 8.6. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 121 9. A Vocabulary for Basic Meta-Data Annotations . . . . . . . . 20 122 9.1. "title" and "description" . . . . . . . . . . . . . . . . 21 123 9.2. "default" . . . . . . . . . . . . . . . . . . . . . . . . 21 124 9.3. "deprecated" . . . . . . . . . . . . . . . . . . . . . . 21 125 9.4. "readOnly" and "writeOnly" . . . . . . . . . . . . . . . 22 126 9.5. "examples" . . . . . . . . . . . . . . . . . . . . . . . 22 127 10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 128 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 129 11.1. Normative References . . . . . . . . . . . . . . . . . . 23 130 11.2. Informative References . . . . . . . . . . . . . . . . . 25 131 Appendix A. Keywords Moved from Validation to Core . . . . . . . 26 132 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 26 133 Appendix C. ChangeLog . . . . . . . . . . . . . . . . . . . . . 27 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 136 1. Introduction 138 JSON Schema can be used to require that a given JSON document (an 139 instance) satisfies a certain number of criteria. These criteria are 140 asserted by using keywords described in this specification. In 141 addition, a set of keywords is also defined to assist in interactive 142 user interface instance generation. 144 This specification will use the concepts, syntax, and terminology 145 defined by the JSON Schema core [json-schema] specification. 147 2. Conventions and Terminology 149 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 150 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 151 document are to be interpreted as described in RFC 2119 [RFC2119]. 153 This specification uses the term "container instance" to refer to 154 both array and object instances. It uses the term "children 155 instances" to refer to array elements or object member values. 157 Elements in an array value are said to be unique if no two elements 158 of this array are equal [json-schema]. 160 3. Overview 162 JSON Schema validation asserts constraints on the structure of 163 instance data. An instance location that satisfies all asserted 164 constraints is then annotated with any keywords that contain non- 165 assertion information, such as descriptive metadata and usage hints. 166 If all locations within the instance satisfy all asserted 167 constraints, then the instance is said to be valid against the 168 schema. 170 Each schema object is independently evaluated against each instance 171 location to which it applies. This greatly simplifies the 172 implementation requirements for validators by ensuring that they do 173 not need to maintain state across the document-wide validation 174 process. 176 This specification defines a set of assertion keywords, as well as a 177 small vocabulary of metadata keywords that can be used to annotate 178 the JSON instance with useful information. The Section 7 keyword is 179 intended primarily as an annotation, but can optionally be used as an 180 assertion. The Section 8 keywords are annotations for working with 181 documents embedded as JSON strings. 183 4. Interoperability Considerations 185 4.1. Validation of String Instances 187 It should be noted that the nul character (\u0000) is valid in a JSON 188 string. An instance to validate may contain a string value with this 189 character, regardless of the ability of the underlying programming 190 language to deal with such data. 192 4.2. Validation of Numeric Instances 194 The JSON specification allows numbers with arbitrary precision, and 195 JSON Schema does not add any such bounds. This means that numeric 196 instances processed by JSON Schema can be arbitrarily large and/or 197 have an arbitrarily long decimal part, regardless of the ability of 198 the underlying programming language to deal with such data. 200 4.3. Regular Expressions 202 Keywords that use regular expressions, or constrain the instance 203 value to be a regular expression, are subject to the interoperability 204 considerations for regular expressions in the JSON Schema Core 205 [json-schema] specification. 207 5. Meta-Schema 209 The current URI for the default JSON Schema dialect meta-schema is 210 https://json-schema.org/draft/2020-12/schema. For schema author 211 convenience, this meta-schema describes a dialect consisting of all 212 vocabularies defined in this specification and the JSON Schema Core 213 specification, as well as two former keywords which are reserved for 214 a transitional period. Individual vocabulary and vocabulary meta- 215 schema URIs are given for each section below. Certain vocabularies 216 are optional to support, which is explained in detail in the relevant 217 sections. 219 Updated vocabulary and meta-schema URIs MAY be published between 220 specification drafts in order to correct errors. Implementations 221 SHOULD consider URIs dated after this specification draft and before 222 the next to indicate the same syntax and semantics as those listed 223 here. 225 6. A Vocabulary for Structural Validation 227 Validation keywords in a schema impose requirements for successful 228 validation of an instance. These keywords are all assertions without 229 any annotation behavior. 231 Meta-schemas that do not use "$vocabulary" SHOULD be considered to 232 require this vocabulary as if its URI were present with a value of 233 true. 235 The current URI for this vocabulary, known as the Validation 236 vocabulary, is: . 239 The current URI for the corresponding meta-schema is: https://json- 240 schema.org/draft/2020-12/meta/validation. 242 6.1. Validation Keywords for Any Instance Type 244 6.1.1. type 246 The value of this keyword MUST be either a string or an array. If it 247 is an array, elements of the array MUST be strings and MUST be 248 unique. 250 String values MUST be one of the six primitive types ("null", 251 "boolean", "object", "array", "number", or "string"), or "integer" 252 which matches any number with a zero fractional part. 254 If the value of "type" is a string, then an instance validates 255 successfully if its type matches the type represented by the value of 256 the string. If the value of "type" is an array, then an instance 257 validates successfully if its type matches any of the types indicated 258 by the strings in the array. 260 6.1.2. enum 262 The value of this keyword MUST be an array. This array SHOULD have 263 at least one element. Elements in the array SHOULD be unique. 265 An instance validates successfully against this keyword if its value 266 is equal to one of the elements in this keyword's array value. 268 Elements in the array might be of any type, including null. 270 6.1.3. const 272 The value of this keyword MAY be of any type, including null. 274 Use of this keyword is functionally equivalent to an "enum" 275 (Section 6.1.2) with a single value. 277 An instance validates successfully against this keyword if its value 278 is equal to the value of the keyword. 280 6.2. Validation Keywords for Numeric Instances (number and integer) 282 6.2.1. multipleOf 284 The value of "multipleOf" MUST be a number, strictly greater than 0. 286 A numeric instance is valid only if division by this keyword's value 287 results in an integer. 289 6.2.2. maximum 291 The value of "maximum" MUST be a number, representing an inclusive 292 upper limit for a numeric instance. 294 If the instance is a number, then this keyword validates only if the 295 instance is less than or exactly equal to "maximum". 297 6.2.3. exclusiveMaximum 299 The value of "exclusiveMaximum" MUST be a number, representing an 300 exclusive upper limit for a numeric instance. 302 If the instance is a number, then the instance is valid only if it 303 has a value strictly less than (not equal to) "exclusiveMaximum". 305 6.2.4. minimum 307 The value of "minimum" MUST be a number, representing an inclusive 308 lower limit for a numeric instance. 310 If the instance is a number, then this keyword validates only if the 311 instance is greater than or exactly equal to "minimum". 313 6.2.5. exclusiveMinimum 315 The value of "exclusiveMinimum" MUST be a number, representing an 316 exclusive lower limit for a numeric instance. 318 If the instance is a number, then the instance is valid only if it 319 has a value strictly greater than (not equal to) "exclusiveMinimum". 321 6.3. Validation Keywords for Strings 323 6.3.1. maxLength 325 The value of this keyword MUST be a non-negative integer. 327 A string instance is valid against this keyword if its length is less 328 than, or equal to, the value of this keyword. 330 The length of a string instance is defined as the number of its 331 characters as defined by RFC 8259 [RFC8259]. 333 6.3.2. minLength 335 The value of this keyword MUST be a non-negative integer. 337 A string instance is valid against this keyword if its length is 338 greater than, or equal to, the value of this keyword. 340 The length of a string instance is defined as the number of its 341 characters as defined by RFC 8259 [RFC8259]. 343 Omitting this keyword has the same behavior as a value of 0. 345 6.3.3. pattern 347 The value of this keyword MUST be a string. This string SHOULD be a 348 valid regular expression, according to the ECMA-262 regular 349 expression dialect. 351 A string instance is considered valid if the regular expression 352 matches the instance successfully. Recall: regular expressions are 353 not implicitly anchored. 355 6.4. Validation Keywords for Arrays 357 6.4.1. maxItems 359 The value of this keyword MUST be a non-negative integer. 361 An array instance is valid against "maxItems" if its size is less 362 than, or equal to, the value of this keyword. 364 6.4.2. minItems 366 The value of this keyword MUST be a non-negative integer. 368 An array instance is valid against "minItems" if its size is greater 369 than, or equal to, the value of this keyword. 371 Omitting this keyword has the same behavior as a value of 0. 373 6.4.3. uniqueItems 375 The value of this keyword MUST be a boolean. 377 If this keyword has boolean value false, the instance validates 378 successfully. If it has boolean value true, the instance validates 379 successfully if all of its elements are unique. 381 Omitting this keyword has the same behavior as a value of false. 383 6.4.4. maxContains 385 The value of this keyword MUST be a non-negative integer. 387 If "contains" is not present within the same schema object, then this 388 keyword has no effect. 390 An instance array is valid against "maxContains" in two ways, 391 depending on the form of the annotation result of an adjacent 392 "contains" [json-schema] keyword. The first way is if the annotation 393 result is an array and the length of that array is less than or equal 394 to the "maxContains" value. The second way is if the annotation 395 result is a boolean "true" and the instance array length is less than 396 or equal to the "maxContains" value. 398 6.4.5. minContains 400 The value of this keyword MUST be a non-negative integer. 402 If "contains" is not present within the same schema object, then this 403 keyword has no effect. 405 An instance array is valid against "minContains" in two ways, 406 depending on the form of the annotation result of an adjacent 407 "contains" [json-schema] keyword. The first way is if the annotation 408 result is an array and the length of that array is greater than or 409 equal to the "minContains" value. The second way is if the 410 annotation result is a boolean "true" and the instance array length 411 is greater than or equal to the "minContains" value. 413 A value of 0 is allowed, but is only useful for setting a range of 414 occurrences from 0 to the value of "maxContains". A value of 0 415 causes "minContains" and "contains" to always pass validation (but 416 validation can still fail against a "maxContains" keyword). 418 Omitting this keyword has the same behavior as a value of 1. 420 6.5. Validation Keywords for Objects 422 6.5.1. maxProperties 424 The value of this keyword MUST be a non-negative integer. 426 An object instance is valid against "maxProperties" if its number of 427 properties is less than, or equal to, the value of this keyword. 429 6.5.2. minProperties 431 The value of this keyword MUST be a non-negative integer. 433 An object instance is valid against "minProperties" if its number of 434 properties is greater than, or equal to, the value of this keyword. 436 Omitting this keyword has the same behavior as a value of 0. 438 6.5.3. required 440 The value of this keyword MUST be an array. Elements of this array, 441 if any, MUST be strings, and MUST be unique. 443 An object instance is valid against this keyword if every item in the 444 array is the name of a property in the instance. 446 Omitting this keyword has the same behavior as an empty array. 448 6.5.4. dependentRequired 450 The value of this keyword MUST be an object. Properties in this 451 object, if any, MUST be arrays. Elements in each array, if any, MUST 452 be strings, and MUST be unique. 454 This keyword specifies properties that are required if a specific 455 other property is present. Their requirement is dependent on the 456 presence of the other property. 458 Validation succeeds if, for each name that appears in both the 459 instance and as a name within this keyword's value, every item in the 460 corresponding array is also the name of a property in the instance. 462 Omitting this keyword has the same behavior as an empty object. 464 7. Vocabularies for Semantic Content With "format" 466 7.1. Foreword 468 Structural validation alone may be insufficient to allow an 469 application to correctly utilize certain values. The "format" 470 annotation keyword is defined to allow schema authors to convey 471 semantic information for a fixed subset of values which are 472 accurately described by authoritative resources, be they RFCs or 473 other external specifications. 475 The value of this keyword is called a format attribute. It MUST be a 476 string. A format attribute can generally only validate a given set 477 of instance types. If the type of the instance to validate is not in 478 this set, validation for this format attribute and instance SHOULD 479 succeed. All format attributes defined in this section apply to 480 strings, but a format attribute can be specified to apply to any 481 instance types defined in the data model defined in the core JSON 482 Schema. [json-schema] 483 // Note that the "type" keyword in this specification defines an 484 // "integer" type which is not part of the data model. Therefore a 485 // format attribute can be limited to numbers, but not specifically 486 // to integers. However, a numeric format can be used alongside the 487 // "type" keyword with a value of "integer", or could be explicitly 488 // defined to always pass if the number is not an integer, which 489 // produces essentially the same behavior as only applying to 490 // integers. 492 The current URI for this vocabulary, known as the Format-Annotation 493 vocabulary, is: . The current URI for the corresponding meta-schema is: 495 https://json-schema.org/draft/2020-12/meta/format-annotation. 496 Implementing support for this vocabulary is REQUIRED. 498 In addition to the Format-Annotation vocabulary, a secondary 499 vocabulary is available for custom meta-schemas that defines "format" 500 as an assertion. The URI for the Format-Assertion vocabulary, is: 501 . The 502 current URI for the corresponding meta-schema is: https://json- 503 schema.org/draft/2020-12/meta/format-assertion. Implementing support 504 for the Format-Assertion vocabulary is OPTIONAL. 506 Specifying both the Format-Annotation and the Format-Assertion 507 vocabularies is functionally equivalent to specifying only the 508 Format-Assertion vocabulary since its requirements are a superset of 509 the Format-Annotation vocabulary. 511 7.2. Implementation Requirements 513 The "format" keyword functions as defined by the vocabulary which is 514 referenced. 516 7.2.1. Format-Annotation Vocabulary 518 The value of format MUST be collected as an annotation, if the 519 implementation supports annotation collection. This enables 520 application-level validation when schema validation is unavailable or 521 inadequate. 523 Implementations MAY still treat "format" as an assertion in addition 524 to an annotation and attempt to validate the value's conformance to 525 the specified semantics. The implementation MUST provide options to 526 enable and disable such evaluation and MUST be disabled by default. 527 Implementations SHOULD document their level of support for such 528 validation. 529 // Specifying the Format-Annotation vocabulary and enabling 530 // validation in an implementation should not be viewed as being 531 // equivalent to specifying the Format-Assertion vocabulary since 532 // implementations are not required to provide full validation 533 // support when the Format-Assertion vocabulary is not specified. 535 When the implementation is configured for assertion behavior, it: 537 SHOULD provide an implementation-specific best effort validation 538 for each format attribute defined below; 540 MAY choose to implement validation of any or all format attributes 541 as a no-op by always producing a validation result of true; 543 // This matches the current reality of implementations, which provide 544 // widely varying levels of validation, including no validation at 545 // all, for some or all format attributes. It is also designed to 546 // encourage relying only on the annotation behavior and performing 547 // semantic validation in the application, which is the recommended 548 // best practice. 550 7.2.2. Format-Assertion Vocabulary 552 When the Format-Assertion vocabulary is declared with a value of 553 true, implementations MUST provide full validation support for all of 554 the formats defined by this specificaion. Implementations that 555 cannot provide full validation support MUST refuse to process the 556 schema. 558 An implementation that supports the Format-Assertion vocabulary: 560 MUST still collect "format" as an annotation if the implementation 561 supports annotation collection; 563 MUST evaluate "format" as an assertion; 565 MUST implement syntactic validation for all format attributes 566 defined in this specification, and for any additional format 567 attributes that it recognizes, such that there exist possible 568 instance values of the correct type that will fail validation. 570 The requirement for minimal validation of format attributes is 571 intentionally vague and permissive, due to the complexity involved in 572 many of the attributes. Note in particular that the requirement is 573 limited to syntactic checking; it is not to be expected that an 574 implementation would send an email, attempt to connect to a URL, or 575 otherwise check the existence of an entity identified by a format 576 instance. 577 // The expectation is that for simple formats such as date-time, 578 // syntactic validation will be thorough. For a complex format such 579 // as email addresses, which are the amalgamation of various 580 // standards and numerous adjustments over time, with obscure and/or 581 // obsolete rules that may or may not be restricted by other 582 // applications making use of the value, a minimal validation is 583 // sufficient. For example, an instance string that does not contain 584 // an "@" is clearly not a valid email address, and an "email" or 585 // "hostname" containing characters outside of 7-bit ASCII is 586 // likewise clearly invalid. 588 It is RECOMMENDED that implementations use a common parsing library 589 for each format, or a well-known regular expression. Implementations 590 SHOULD clearly document how and to what degree each format attribute 591 is validated. 593 The standard core and validation meta-schema (Section 5) includes 594 this vocabulary in its "$vocabulary" keyword with a value of false, 595 since by default implementations are not required to support this 596 keyword as an assertion. Supporting the format vocabulary with a 597 value of true is understood to greatly increase code size and in some 598 cases execution time, and will not be appropriate for all 599 implementations. 601 7.2.3. Custom format attributes 603 Implementations MAY support custom format attributes. Save for 604 agreement between parties, schema authors SHALL NOT expect a peer 605 implementation to support such custom format attributes. An 606 implementation MUST NOT fail to collect unknown formats as 607 annotations. When the Format-Assertion vocabulary is specified, 608 implementations MUST fail upon encountering unknown formats. 610 Vocabularies do not support specifically declaring different value 611 sets for keywords. Due to this limitation, and the historically 612 uneven implementation of this keyword, it is RECOMMENDED to define 613 additional keywords in a custom vocabulary rather than additional 614 format attributes if interoperability is desired. 616 7.3. Defined Formats 617 7.3.1. Dates, Times, and Duration 619 These attributes apply to string instances. 621 Date and time format names are derived from RFC 3339, section 5.6 622 [RFC3339]. The duration format is from the ISO 8601 ABNF as given in 623 Appendix A of RFC 3339. 625 Implementations supporting formats SHOULD implement support for the 626 following attributes: 628 date-time: A string instance is valid against this attribute if it 629 is a valid representation according to the "date-time' ABNF rule 630 (referenced above) 632 date: A string instance is valid against this attribute if it is a 633 valid representation according to the "full-date" ABNF rule 634 (referenced above) 636 time: A string instance is valid against this attribute if it is a 637 valid representation according to the "full-time" ABNF rule 638 (referenced above) 640 duration: A string instance is valid against this attribute if it is 641 a valid representation according to the "duration" ABNF rule 642 (referenced above) 644 Implementations MAY support additional attributes using the other 645 format names defined anywhere in that RFC. If "full-date" or "full- 646 time" are implemented, the corresponding short form ("date" or "time" 647 respectively) MUST be implemented, and MUST behave identically. 648 Implementations SHOULD NOT define extension attributes with any name 649 matching an RFC 3339 format unless it validates according to the 650 rules of that format. 651 // There is not currently consensus on the need for supporting all 652 // RFC 3339 formats, so this approach of reserving the namespace will 653 // encourage experimentation without committing to the entire set. 654 // Either the format implementation requirements will become more 655 // flexible in general, or these will likely either be promoted to 656 // fully specified attributes or dropped. 658 7.3.2. Email Addresses 660 These attributes apply to string instances. 662 A string instance is valid against these attributes if it is a valid 663 Internet email address as follows: 665 email: As defined by the "Mailbox" ABNF rule in RFC 5321, section 666 4.1.2 [RFC5321]. 668 idn-email: As defined by the extended "Mailbox" ABNF rule in RFC 669 6531, section 3.3 [RFC6531]. 671 Note that all strings valid against the "email" attribute are also 672 valid against the "idn-email" attribute. 674 7.3.3. Hostnames 676 These attributes apply to string instances. 678 A string instance is valid against these attributes if it is a valid 679 representation for an Internet hostname as follows: 681 hostname: As defined by RFC 1123, section 2.1 [RFC1123], including 682 host names produced using the Punycode algorithm specified in RFC 683 5891, section 4.4 [RFC5891]. 685 idn-hostname: As defined by either RFC 1123 as for hostname, or an 686 internationalized hostname as defined by RFC 5890, section 2.3.2.3 687 [RFC5890]. 689 Note that all strings valid against the "hostname" attribute are also 690 valid against the "idn-hostname" attribute. 692 7.3.4. IP Addresses 694 These attributes apply to string instances. 696 A string instance is valid against these attributes if it is a valid 697 representation of an IP address as follows: 699 ipv4: An IPv4 address according to the "dotted-quad" ABNF syntax as 700 defined in RFC 2673, section 3.2 [RFC2673]. 702 ipv6: An IPv6 address as defined in RFC 4291, section 2.2 [RFC4291]. 704 7.3.5. Resource Identifiers 706 These attributes apply to string instances. 708 uri: A string instance is valid against this attribute if it is a 709 valid URI, according to [RFC3986]. 711 uri-reference: A string instance is valid against this attribute if 712 it is a valid URI Reference (either a URI or a relative- 713 reference), according to [RFC3986]. 715 iri: A string instance is valid against this attribute if it is a 716 valid IRI, according to [RFC3987]. 718 iri-reference: A string instance is valid against this attribute if 719 it is a valid IRI Reference (either an IRI or a relative- 720 reference), according to [RFC3987]. 722 uuid: A string instance is valid against this attribute if it is a 723 valid string representation of a UUID, according to [RFC4122]. 725 Note that all valid URIs are valid IRIs, and all valid URI References 726 are also valid IRI References. 728 Note also that the "uuid" format is for plain UUIDs, not UUIDs in 729 URNs. An example is "f81d4fae-7dec-11d0-a765-00a0c91e6bf6". For 730 UUIDs as URNs, use the "uri" format, with a "pattern" regular 731 expression of "^urn:uuid:" to indicate the URI scheme and URN 732 namespace. 734 7.3.6. uri-template 736 This attribute applies to string instances. 738 A string instance is valid against this attribute if it is a valid 739 URI Template (of any level), according to [RFC6570]. 741 Note that URI Templates may be used for IRIs; there is no separate 742 IRI Template specification. 744 7.3.7. JSON Pointers 746 These attributes apply to string instances. 748 json-pointer: A string instance is valid against this attribute if 749 it is a valid JSON string representation of a JSON Pointer, 750 according to RFC 6901, section 5 [RFC6901]. 752 relative-json-pointer: A string instance is valid against this 753 attribute if it is a valid Relative JSON Pointer 754 [relative-json-pointer]. 756 To allow for both absolute and relative JSON Pointers, use "anyOf" or 757 "oneOf" to indicate support for either format. 759 7.3.8. regex 761 This attribute applies to string instances. 763 A regular expression, which SHOULD be valid according to the ECMA-262 764 [ecma262] regular expression dialect. 766 Implementations that validate formats MUST accept at least the subset 767 of ECMA-262 defined in the Regular Expressions (Section 4.3) section 768 of this specification, and SHOULD accept all valid ECMA-262 769 expressions. 771 8. A Vocabulary for the Contents of String-Encoded Data 773 8.1. Foreword 775 Annotations defined in this section indicate that an instance 776 contains non-JSON data encoded in a JSON string. 778 These properties provide additional information required to interpret 779 JSON data as rich multimedia documents. They describe the type of 780 content, how it is encoded, and/or how it may be validated. They do 781 not function as validation assertions; a malformed string-encoded 782 document MUST NOT cause the containing instance to be considered 783 invalid. 785 Meta-schemas that do not use "$vocabulary" SHOULD be considered to 786 require this vocabulary as if its URI were present with a value of 787 true. 789 The current URI for this vocabulary, known as the Content vocabulary, 790 is: . 792 The current URI for the corresponding meta-schema is: https://json- 793 schema.org/draft/2020-12/meta/content. 795 8.2. Implementation Requirements 797 Due to security and performance concerns, as well as the open-ended 798 nature of possible content types, implementations MUST NOT 799 automatically decode, parse, and/or validate the string contents by 800 default. This additionally supports the use case of embedded 801 documents intended for processing by a different consumer than that 802 which processed the containing document. 804 All keywords in this section apply only to strings, and have no 805 effect on other data types. 807 Implementations MAY offer the ability to decode, parse, and/or 808 validate the string contents automatically. However, it MUST NOT 809 perform these operations by default, and MUST provide the validation 810 result of each string-encoded document separately from the enclosing 811 document. This process SHOULD be equivalent to fully evaluating the 812 instance against the original schema, followed by using the 813 annotations to decode, parse, and/or validate each string-encoded 814 document. 815 // For now, the exact mechanism of performing and returning parsed 816 // data and/or validation results from such an automatic decoding, 817 // parsing, and validating feature is left unspecified. Should such 818 // a feature prove popular, it may be specified more thoroughly in a 819 // future draft. 821 See also the Security Considerations (Section 10) sections for 822 possible vulnerabilities introduced by automatically processing the 823 instance string according to these keywords. 825 8.3. contentEncoding 827 If the instance value is a string, this property defines that the 828 string SHOULD be interpreted as encoded binary data and decoded using 829 the encoding named by this property. 831 Possible values indicating base 16, 32, and 64 encodings with several 832 variations are listed in RFC 4648 [RFC4648]. Additionally, sections 833 6.7 and 6.8 of RFC 2045 [RFC2045] provide encodings used in MIME. 834 This keyword is derived from MIME's Content-Transfer-Encoding header, 835 which was designed to map binary data into ASCII characters. It is 836 not related to HTTP's Content-Encoding header, which is used to 837 encode (e.g. compress or encrypt) the content of HTTP request and 838 responses. 840 As "base64" is defined in both RFCs, the definition from RFC 4648 841 SHOULD be assumed unless the string is specifically intended for use 842 in a MIME context. Note that all of these encodings result in 843 strings consisting only of 7-bit ASCII characters. Therefore, this 844 keyword has no meaning for strings containing characters outside of 845 that range. 847 If this keyword is absent, but "contentMediaType" is present, this 848 indicates that the encoding is the identity encoding, meaning that no 849 transformation was needed in order to represent the content in a 850 UTF-8 string. 852 The value of this property MUST be a string. 854 8.4. contentMediaType 856 If the instance is a string, this property indicates the media type 857 of the contents of the string. If "contentEncoding" is present, this 858 property describes the decoded string. 860 The value of this property MUST be a string, which MUST be a media 861 type, as defined by RFC 2046 [RFC2046]. 863 8.5. contentSchema 865 If the instance is a string, and if "contentMediaType" is present, 866 this property contains a schema which describes the structure of the 867 string. 869 This keyword MAY be used with any media type that can be mapped into 870 JSON Schema's data model. 872 The value of this property MUST be a valid JSON schema. It SHOULD be 873 ignored if "contentMediaType" is not present. 875 8.6. Example 877 Here is an example schema, illustrating the use of "contentEncoding" 878 and "contentMediaType": 880 { 881 "type": "string", 882 "contentEncoding": "base64", 883 "contentMediaType": "image/png" 884 } 886 Instances described by this schema are expected to be strings, and 887 their values should be interpretable as base64-encoded PNG images. 889 Another example: 891 { 892 "type": "string", 893 "contentMediaType": "text/html" 894 } 896 Instances described by this schema are expected to be strings 897 containing HTML, using whatever character set the JSON string was 898 decoded into. Per section 8.1 of RFC 8259 [RFC8259], outside of an 899 entirely closed system, this MUST be UTF-8. 901 This example describes a JWT that is MACed using the HMAC SHA-256 902 algorithm, and requires the "iss" and "exp" fields in its claim set. 904 { 905 "type": "string", 906 "contentMediaType": "application/jwt", 907 "contentSchema": { 908 "type": "array", 909 "minItems": 2, 910 "prefixItems": [ 911 { 912 "const": { 913 "typ": "JWT", 914 "alg": "HS256" 915 } 916 }, 917 { 918 "type": "object", 919 "required": ["iss", "exp"], 920 "properties": { 921 "iss": {"type": "string"}, 922 "exp": {"type": "integer"} 923 } 924 } 925 ] 926 } 927 } 929 Note that "contentEncoding" does not appear. While the "application/ 930 jwt" media type makes use of base64url encoding, that is defined by 931 the media type, which determines how the JWT string is decoded into a 932 list of two JSON data structures: first the header, and then the 933 payload. Since the JWT media type ensures that the JWT can be 934 represented in a JSON string, there is no need for further encoding 935 or decoding. 937 9. A Vocabulary for Basic Meta-Data Annotations 939 These general-purpose annotation keywords provide commonly used 940 information for documentation and user interface display purposes. 941 They are not intended to form a comprehensive set of features. 942 Rather, additional vocabularies can be defined for more complex 943 annotation-based applications. 945 Meta-schemas that do not use "$vocabulary" SHOULD be considered to 946 require this vocabulary as if its URI were present with a value of 947 true. 949 The current URI for this vocabulary, known as the Meta-Data 950 vocabulary, is: . 953 The current URI for the corresponding meta-schema is: https://json- 954 schema.org/draft/2020-12/meta/meta-data. 956 9.1. "title" and "description" 958 The value of both of these keywords MUST be a string. 960 Both of these keywords can be used to decorate a user interface with 961 information about the data produced by this user interface. A title 962 will preferably be short, whereas a description will provide 963 explanation about the purpose of the instance described by this 964 schema. 966 9.2. "default" 968 There are no restrictions placed on the value of this keyword. When 969 multiple occurrences of this keyword are applicable to a single sub- 970 instance, implementations SHOULD remove duplicates. 972 This keyword can be used to supply a default JSON value associated 973 with a particular schema. It is RECOMMENDED that a default value be 974 valid against the associated schema. 976 9.3. "deprecated" 978 The value of this keyword MUST be a boolean. When multiple 979 occurrences of this keyword are applicable to a single sub-instance, 980 applications SHOULD consider the instance location to be deprecated 981 if any occurrence specifies a true value. 983 If "deprecated" has a value of boolean true, it indicates that 984 applications SHOULD refrain from usage of the declared property. It 985 MAY mean the property is going to be removed in the future. 987 A root schema containing "deprecated" with a value of true indicates 988 that the entire resource being described MAY be removed in the 989 future. 991 The "deprecated" keyword applies to each instance location to which 992 the schema object containing the keyword successfully applies. This 993 can result in scenarios where every array item or object property is 994 deprecated even though the containing array or object is not. 996 Omitting this keyword has the same behavior as a value of false. 998 9.4. "readOnly" and "writeOnly" 1000 The value of these keywords MUST be a boolean. When multiple 1001 occurrences of these keywords are applicable to a single sub- 1002 instance, the resulting behavior SHOULD be as for a true value if any 1003 occurrence specifies a true value, and SHOULD be as for a false value 1004 otherwise. 1006 If "readOnly" has a value of boolean true, it indicates that the 1007 value of the instance is managed exclusively by the owning authority, 1008 and attempts by an application to modify the value of this property 1009 are expected to be ignored or rejected by that owning authority. 1011 An instance document that is marked as "readOnly" for the entire 1012 document MAY be ignored if sent to the owning authority, or MAY 1013 result in an error, at the authority's discretion. 1015 If "writeOnly" has a value of boolean true, it indicates that the 1016 value is never present when the instance is retrieved from the owning 1017 authority. It can be present when sent to the owning authority to 1018 update or create the document (or the resource it represents), but it 1019 will not be included in any updated or newly created version of the 1020 instance. 1022 An instance document that is marked as "writeOnly" for the entire 1023 document MAY be returned as a blank document of some sort, or MAY 1024 produce an error upon retrieval, or have the retrieval request 1025 ignored, at the authority's discretion. 1027 For example, "readOnly" would be used to mark a database-generated 1028 serial number as read-only, while "writeOnly" would be used to mark a 1029 password input field. 1031 These keywords can be used to assist in user interface instance 1032 generation. In particular, an application MAY choose to use a widget 1033 that hides input values as they are typed for write-only fields. 1035 Omitting these keywords has the same behavior as values of false. 1037 9.5. "examples" 1039 The value of this keyword MUST be an array. There are no 1040 restrictions placed on the values within the array. When multiple 1041 occurrences of this keyword are applicable to a single sub-instance, 1042 implementations MUST provide a flat array of all values rather than 1043 an array of arrays. 1045 This keyword can be used to provide sample JSON values associated 1046 with a particular schema, for the purpose of illustrating usage. It 1047 is RECOMMENDED that these values be valid against the associated 1048 schema. 1050 Implementations MAY use the value(s) of "default", if present, as an 1051 additional example. If "examples" is absent, "default" MAY still be 1052 used in this manner. 1054 10. Security Considerations 1056 JSON Schema validation defines a vocabulary for JSON Schema core and 1057 concerns all the security considerations listed there. 1059 JSON Schema validation allows the use of Regular Expressions, which 1060 have numerous different (often incompatible) implementations. Some 1061 implementations allow the embedding of arbitrary code, which is 1062 outside the scope of JSON Schema and MUST NOT be permitted. Regular 1063 expressions can often also be crafted to be extremely expensive to 1064 compute (with so-called "catastrophic backtracking"), resulting in a 1065 denial-of-service attack. 1067 Implementations that support validating or otherwise evaluating 1068 instance string data based on "contentEncoding" and/or 1069 "contentMediaType" are at risk of evaluating data in an unsafe way 1070 based on misleading information. Applications can mitigate this risk 1071 by only performing such processing when a relationship between the 1072 schema and instance is established (e.g., they share the same 1073 authority). 1075 Processing a media type or encoding is subject to the security 1076 considerations of that media type or encoding. For example, the 1077 security considerations of RFC 4329 Scripting Media Types [RFC4329] 1078 apply when processing JavaScript or ECMAScript encoded within a JSON 1079 string. 1081 11. References 1083 11.1. Normative References 1085 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1086 Requirement Levels", BCP 14, RFC 2119, 1087 DOI 10.17487/RFC2119, March 1997, 1088 . 1090 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 1091 Application and Support", STD 3, RFC 1123, 1092 DOI 10.17487/RFC1123, October 1989, 1093 . 1095 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1096 Extensions (MIME) Part One: Format of Internet Message 1097 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 1098 . 1100 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1101 Extensions (MIME) Part Two: Media Types", RFC 2046, 1102 DOI 10.17487/RFC2046, November 1996, 1103 . 1105 [RFC2673] Crawford, M., "Binary Labels in the Domain Name System", 1106 RFC 2673, DOI 10.17487/RFC2673, August 1999, 1107 . 1109 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1110 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1111 . 1113 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1114 Resource Identifier (URI): Generic Syntax", STD 66, 1115 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1116 . 1118 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1119 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 1120 January 2005, . 1122 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1123 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1124 DOI 10.17487/RFC4122, July 2005, 1125 . 1127 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1128 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 1129 2006, . 1131 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1132 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1133 . 1135 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 1136 DOI 10.17487/RFC5321, October 2008, 1137 . 1139 [RFC5890] Klensin, J., "Internationalized Domain Names for 1140 Applications (IDNA): Definitions and Document Framework", 1141 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1142 . 1144 [RFC5891] Klensin, J., "Internationalized Domain Names in 1145 Applications (IDNA): Protocol", RFC 5891, 1146 DOI 10.17487/RFC5891, August 2010, 1147 . 1149 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 1150 and D. Orchard, "URI Template", RFC 6570, 1151 DOI 10.17487/RFC6570, March 2012, 1152 . 1154 [RFC6531] Yao, J. and W. Mao, "SMTP Extension for Internationalized 1155 Email", RFC 6531, DOI 10.17487/RFC6531, February 2012, 1156 . 1158 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 1159 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 1160 DOI 10.17487/RFC6901, April 2013, 1161 . 1163 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1164 Interchange Format", STD 90, RFC 8259, 1165 DOI 10.17487/RFC8259, December 2017, 1166 . 1168 [ecma262] "ECMA-262, 11th edition specification", June 2020, 1169 . 1171 [relative-json-pointer] 1172 Luff, G., Andrews, H., and B. Hutton, Ed., "Relative JSON 1173 Pointers", Work in Progress, Internet-Draft, draft- 1174 handrews-relative-json-pointer-01, December 2020, 1175 . 1178 [json-schema] 1179 Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON 1180 Schema: A Media Type for Describing JSON Documents", Work 1181 in Progress, Internet-Draft, draft-bhutton-json-schema-01, 1182 June 2022, . 1185 11.2. Informative References 1187 [RFC4329] Hoehrmann, B., "Scripting Media Types", RFC 4329, 1188 DOI 10.17487/RFC4329, April 2006, 1189 . 1191 Appendix A. Keywords Moved from Validation to Core 1193 Several keywords have been moved from this document into the Core 1194 Specification [json-schema] as of this draft, in some cases with re- 1195 naming or other changes. This affects the following former 1196 validation keywords: 1198 "definitions" Renamed to "$defs" to match "$ref" and be shorter to 1199 type. Schema vocabulary authors SHOULD NOT define a "definitions" 1200 keyword with different behavior in order to avoid invalidating 1201 schemas that still use the older name. While "definitions" is 1202 absent in the single-vocabulary meta-schemas referenced by this 1203 document, it remains present in the default meta-schema, and 1204 implementations SHOULD assume that "$defs" and "definitions" have 1205 the same behavior when that meta-schema is used. 1207 "allOf", "anyOf", "oneOf", "not", "if", "then", "else", "items", 1208 "additionalItems", "contains", "propertyNames", "properties", 1209 "patternProperties", "additionalProperties" All of these keywords 1210 apply subschemas to the instance and combine their results, 1211 without asserting any conditions of their own. Without assertion 1212 keywords, these applicators can only cause assertion failures by 1213 using the false boolean schema, or by inverting the result of the 1214 true boolean schema (or equivalent schema objects). For this 1215 reason, they are better defined as a generic mechanism on which 1216 validation, hyper-schema, and extension vocabularies can all be 1217 based. 1219 "dependencies" This keyword had two different modes of behavior, 1220 which made it relatively challenging to implement and reason 1221 about. The schema form has been moved to Core and renamed to 1222 "dependentSchemas", as part of the applicator vocabulary. It is 1223 analogous to "properties", except that instead of applying its 1224 subschema to the property value, it applies it to the object 1225 containing the property. The property name array form is retained 1226 here and renamed to "dependentRequired", as it is an assertion 1227 which is a shortcut for the conditional use of the "required" 1228 assertion keyword. 1230 Appendix B. Acknowledgments 1232 Thanks to Gary Court, Francis Galiegue, Kris Zyp, and Geraint Luff 1233 for their work on the initial drafts of JSON Schema. 1235 Thanks to Jason Desrosiers, Daniel Perrett, Erik Wilde, Evgeny 1236 Poberezkin, Brad Bowman, Gowry Sankar, Donald Pipowitch, Dave Finlay, 1237 Denis Laxalde, Phil Sturgeon, Shawn Silverman, and Karen Etheridge 1238 for their submissions and patches to the document. 1240 Appendix C. ChangeLog 1242 // This section to be removed before leaving Internet-Draft status. 1244 draft-bhutton-json-schema-validation-01 1245 * Improve and clarify the "minContains" keyword explanation 1247 * Remove the use of "production" in favour of "ABNF rule" 1249 draft-bhutton-json-schema-validation-00 1250 * Correct email format RFC reference to 5321 instead of 5322 1252 * Clarified the set and meaning of "contentEncoding" values 1254 * Reference ECMA-262, 11th edition for regular expression support 1256 * Split "format" into an annotation only vocabulary and an 1257 assertion vocabulary 1259 * Clarify "deprecated" when applicable to arrays 1261 draft-handrews-json-schema-validation-02 1262 * Grouped keywords into formal vocabularies 1264 * Update "format" implementation requirements in terms of 1265 vocabularies 1267 * By default, "format" MUST NOT be validated, although validation 1268 can be enabled 1270 * A vocabulary declaration can be used to require "format" 1271 validation 1273 * Moved "definitions" to the core spec as "$defs" 1275 * Moved applicator keywords to the core spec 1277 * Renamed the array form of "dependencies" to 1278 "dependentRequired", moved the schema form to the core spec 1280 * Specified all "content*" keywords as annotations, not 1281 assertions 1283 * Added "contentSchema" to allow applying a schema to a string- 1284 encoded document 1286 * Also allow RFC 4648 encodings in "contentEncoding" 1288 * Added "minContains" and "maxContains" 1290 * Update RFC reference for "hostname" and "idn-hostname" 1292 * Add "uuid" and "duration" formats 1294 draft-handrews-json-schema-validation-01 1295 * This draft is purely a clarification with no functional changes 1297 * Provided the general principle behind ignoring annotations 1298 under "not" and similar cases 1300 * Clarified "if"/"then"/"else" validation interactions 1302 * Clarified "if"/"then"/"else" behavior for annotation 1304 * Minor formatting and cross-referencing improvements 1306 draft-handrews-json-schema-validation-00 1307 * Added "if"/"then"/"else" 1309 * Classify keywords as assertions or annotations per the core 1310 spec 1312 * Warn of possibly removing "dependencies" in the future 1314 * Grouped validation keywords into sub-sections for readability 1316 * Moved "readOnly" from hyper-schema to validation meta-data 1318 * Added "writeOnly" 1320 * Added string-encoded media section, with former hyper-schema 1321 "media" keywords 1323 * Restored "regex" format (removal was unintentional) 1325 * Added "date" and "time" formats, and reserved additional RFC 1326 3339 format names 1328 * I18N formats: "iri", "iri-reference", "idn-hostname", "idn- 1329 email" 1331 * Clarify that "json-pointer" format means string encoding, not 1332 URI fragment 1334 * Fixed typo that inverted the meaning of "minimum" and 1335 "exclusiveMinimum" 1337 * Move format syntax references into Normative References 1339 * JSON is a normative requirement 1341 draft-wright-json-schema-validation-01 1342 * Standardized on hyphenated format names with full words 1343 ("uriref" becomes "uri-reference") 1345 * Add the formats "uri-template" and "json-pointer" 1347 * Changed "exclusiveMaximum"/"exclusiveMinimum" from boolean 1348 modifiers of "maximum"/"minimum" to independent numeric fields. 1350 * Split the additionalItems/items into two sections 1352 * Reworked properties/patternProperties/additionalProperties 1353 definition 1355 * Added "examples" keyword 1357 * Added "contains" keyword 1359 * Allow empty "required" and "dependencies" arrays 1361 * Fixed "type" reference to primitive types 1363 * Added "const" keyword 1365 * Added "propertyNames" keyword 1367 draft-wright-json-schema-validation-00 1368 * Added additional security considerations 1370 * Removed reference to "latest version" meta-schema, use numbered 1371 version instead 1373 * Rephrased many keyword definitions for brevity 1375 * Added "uriref" format that also allows relative URI references 1377 draft-fge-json-schema-validation-00 1378 * Initial draft. 1380 * Salvaged from draft v3. 1382 * Redefine the "required" keyword. 1384 * Remove "extends", "disallow" 1386 * Add "anyOf", "allOf", "oneOf", "not", "definitions", 1387 "minProperties", "maxProperties". 1389 * "dependencies" member values can no longer be single strings; 1390 at least one element is required in a property dependency 1391 array. 1393 * Rename "divisibleBy" to "multipleOf". 1395 * "type" arrays can no longer have schemas; remove "any" as a 1396 possible value. 1398 * Rework the "format" section; make support optional. 1400 * "format": remove attributes "phone", "style", "color"; rename 1401 "ip-address" to "ipv4"; add references for all attributes. 1403 * Provide algorithms to calculate schema(s) for array/object 1404 instances. 1406 * Add interoperability considerations. 1408 Authors' Addresses 1410 Austin Wright (editor) 1411 Email: aaa@bzfx.net 1413 Henry Andrews (editor) 1414 Email: andrews_henry@yahoo.com 1416 Ben Hutton (editor) 1417 Postman 1418 Email: ben@jsonschema.dev 1419 URI: https://jsonschema.dev