idnits 2.17.1 draft-wright-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 (April 15, 2017) is 2566 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 2373 (Obsoleted by RFC 3513) -- Obsolete informational reference (is this intentional?): RFC 2673 (Obsoleted by RFC 6891) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 4 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 G. Luff 5 Expires: October 17, 2017 6 H. Andrews, Ed. 7 Cloudflare, Inc. 8 April 15, 2017 10 JSON Schema Validation: A Vocabulary for Structural Validation of JSON 11 draft-wright-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 . 26 For additional information, see . 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 http://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 October 17, 2017. 48 Copyright Notice 50 Copyright (c) 2017 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 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4 67 3. Interoperability considerations . . . . . . . . . . . . . . . 4 68 3.1. Validation of string instances . . . . . . . . . . . . . 4 69 3.2. Validation of numeric instances . . . . . . . . . . . . . 4 70 3.3. Regular expressions . . . . . . . . . . . . . . . . . . . 4 71 4. General validation considerations . . . . . . . . . . . . . . 5 72 4.1. Keywords and instance primitive types . . . . . . . . . . 5 73 4.2. Validation of primitive types and child values . . . . . 5 74 4.3. Constraints and missing keywords . . . . . . . . . . . . 6 75 4.4. Keyword independence . . . . . . . . . . . . . . . . . . 6 76 5. Meta-schema . . . . . . . . . . . . . . . . . . . . . . . . . 6 77 6. Validation keywords . . . . . . . . . . . . . . . . . . . . . 6 78 6.1. multipleOf . . . . . . . . . . . . . . . . . . . . . . . 6 79 6.2. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 6 80 6.3. exclusiveMaximum . . . . . . . . . . . . . . . . . . . . 7 81 6.4. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 7 82 6.5. exclusiveMinimum . . . . . . . . . . . . . . . . . . . . 7 83 6.6. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 7 84 6.7. minLength . . . . . . . . . . . . . . . . . . . . . . . . 7 85 6.8. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 8 86 6.9. items . . . . . . . . . . . . . . . . . . . . . . . . . . 8 87 6.10. additionalItems . . . . . . . . . . . . . . . . . . . . . 8 88 6.11. maxItems . . . . . . . . . . . . . . . . . . . . . . . . 9 89 6.12. minItems . . . . . . . . . . . . . . . . . . . . . . . . 9 90 6.13. uniqueItems . . . . . . . . . . . . . . . . . . . . . . . 9 91 6.14. contains . . . . . . . . . . . . . . . . . . . . . . . . 9 92 6.15. maxProperties . . . . . . . . . . . . . . . . . . . . . . 9 93 6.16. minProperties . . . . . . . . . . . . . . . . . . . . . . 9 94 6.17. required . . . . . . . . . . . . . . . . . . . . . . . . 10 95 6.18. properties . . . . . . . . . . . . . . . . . . . . . . . 10 96 6.19. patternProperties . . . . . . . . . . . . . . . . . . . . 10 97 6.20. additionalProperties . . . . . . . . . . . . . . . . . . 11 98 6.21. dependencies . . . . . . . . . . . . . . . . . . . . . . 11 99 6.22. propertyNames . . . . . . . . . . . . . . . . . . . . . . 11 100 6.23. enum . . . . . . . . . . . . . . . . . . . . . . . . . . 12 101 6.24. const . . . . . . . . . . . . . . . . . . . . . . . . . . 12 102 6.25. type . . . . . . . . . . . . . . . . . . . . . . . . . . 12 103 6.26. allOf . . . . . . . . . . . . . . . . . . . . . . . . . . 12 104 6.27. anyOf . . . . . . . . . . . . . . . . . . . . . . . . . . 12 105 6.28. oneOf . . . . . . . . . . . . . . . . . . . . . . . . . . 13 106 6.29. not . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 107 7. Metadata keywords . . . . . . . . . . . . . . . . . . . . . . 13 108 7.1. definitions . . . . . . . . . . . . . . . . . . . . . . . 13 109 7.2. "title" and "description" . . . . . . . . . . . . . . . . 14 110 7.3. "default" . . . . . . . . . . . . . . . . . . . . . . . . 14 111 7.4. "examples" . . . . . . . . . . . . . . . . . . . . . . . 14 112 8. Semantic validation with "format" . . . . . . . . . . . . . . 14 113 8.1. Foreword . . . . . . . . . . . . . . . . . . . . . . . . 14 114 8.2. Implementation requirements . . . . . . . . . . . . . . . 15 115 8.3. Defined formats . . . . . . . . . . . . . . . . . . . . . 15 116 8.3.1. date-time . . . . . . . . . . . . . . . . . . . . . . 15 117 8.3.2. email . . . . . . . . . . . . . . . . . . . . . . . . 15 118 8.3.3. hostname . . . . . . . . . . . . . . . . . . . . . . 15 119 8.3.4. ipv4 . . . . . . . . . . . . . . . . . . . . . . . . 15 120 8.3.5. ipv6 . . . . . . . . . . . . . . . . . . . . . . . . 16 121 8.3.6. uri . . . . . . . . . . . . . . . . . . . . . . . . . 16 122 8.3.7. uri-reference . . . . . . . . . . . . . . . . . . . . 16 123 8.3.8. uri-template . . . . . . . . . . . . . . . . . . . . 16 124 8.3.9. json-pointer . . . . . . . . . . . . . . . . . . . . 16 125 9. Security considerations . . . . . . . . . . . . . . . . . . . 16 126 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 127 10.1. Normative References . . . . . . . . . . . . . . . . . . 17 128 10.2. Informative References . . . . . . . . . . . . . . . . . 17 129 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 19 130 Appendix B. ChangeLog . . . . . . . . . . . . . . . . . . . . . 19 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 133 1. Introduction 135 JSON Schema can be used to require that a given JSON document (an 136 instance) satisfies a certain number of criteria. These criteria are 137 asserted by using keywords described in this specification. In 138 addition, a set of keywords is also defined to assist in interactive 139 user interface instance generation. 141 This specification will use the terminology defined by the JSON 142 Schema core [json-schema] specification. 144 2. Conventions and Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 148 document are to be interpreted as described in RFC 2119 [RFC2119]. 150 This specification uses the term "container instance" to refer to 151 both array and object instances. It uses the term "children 152 instances" to refer to array elements or object member values. 154 Elements in an array value are said to be unique if no two elements 155 of this array are equal [json-schema]. 157 3. Interoperability considerations 159 3.1. Validation of string instances 161 It should be noted that the nul character (\u0000) is valid in a JSON 162 string. An instance to validate may contain a string value with this 163 character, regardless of the ability of the underlying programming 164 language to deal with such data. 166 3.2. Validation of numeric instances 168 The JSON specification allows numbers with arbitrary precision, and 169 JSON Schema does not add any such bounds. This means that numeric 170 instances processed by JSON Schema can be arbitrarily large and/or 171 have an arbitrarily long decimal part, regardless of the ability of 172 the underlying programming language to deal with such data. 174 3.3. Regular expressions 176 Two validation keywords, "pattern" and "patternProperties", use 177 regular expressions to express constraints. These regular 178 expressions SHOULD be valid according to the ECMA 262 [ecma262] 179 regular expression dialect. 181 Furthermore, given the high disparity in regular expression 182 constructs support, schema authors SHOULD limit themselves to the 183 following regular expression tokens: 185 individual Unicode characters, as defined by the JSON 186 specification [RFC7159]; 188 simple character classes ([abc]), range character classes ([a-z]); 190 complemented character classes ([^abc], [^a-z]); 191 simple quantifiers: "+" (one or more), "*" (zero or more), "?" 192 (zero or one), and their lazy versions ("+?", "*?", "??"); 194 range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at 195 least x, at most y, occurrences), {x,} (x occurrences or more), 196 and their lazy versions; 198 the beginning-of-input ("^") and end-of-input ("$") anchors; 200 simple grouping ("(...)") and alternation ("|"). 202 Finally, implementations MUST NOT take regular expressions to be 203 anchored, neither at the beginning nor at the end. This means, for 204 instance, the pattern "es" matches "expression". 206 4. General validation considerations 208 4.1. Keywords and instance primitive types 210 Most validation keywords only constrain values within a certain 211 primitive type. When the type of the instance is not of the type 212 targeted by the keyword, the validation succeeds. 214 For example, the "maxLength" keyword will only restrict certain 215 strings (that are too long) from being valid. If the instance is a 216 number, boolean, null, array, or object, the keyword passes 217 validation. 219 4.2. Validation of primitive types and child values 221 Two of the primitive types, array and object, allow for child values. 222 The validation of the primitive type is considered separately from 223 the validation of child instances. 225 For arrays, primitive type validation consists of validating 226 restrictions on length with "minItems" and "maxItems", while "items" 227 and "additionalItems" determine which subschemas apply to which 228 elements of the array. In addition, "uniqueItems" and "contains" 229 validate array contents as a whole. 231 For objects, primitive type validation consists of validating 232 restrictions on which and how many properties appear with "required", 233 "minProperties", "maxProperties", "propertyNames", and the string 234 array form of "dependencies", while "properties", 235 "patternProperties", and "additionalProperties" determine which 236 subschemas apply to which object property values. In addition, the 237 schema form of "dependencies" validates the object as a whole based 238 on the presence of specific property names. 240 4.3. Constraints and missing keywords 242 Each JSON Schema validation keyword adds constraints that an instance 243 must satisfy in order to successfully validate. 245 Validation keywords that are missing never restrict validation. In 246 some cases, this no-op behavior is identical to a keyword that exists 247 with certain values, and these values are noted where known. 249 4.4. Keyword independence 251 Validation keywords typically operate independently, without 252 affecting each other's outcomes. 254 For schema author convenience, there are some exceptions: 256 "additionalProperties", whose behavior is defined in terms of 257 "properties" and "patternProperties"; and 259 "additionalItems", whose behavior is defined in terms of "items". 261 5. Meta-schema 263 The current URI for the JSON Schema Validation is . 266 6. Validation keywords 268 Validation keywords in a schema impose requirements for successful 269 validation of an instance. 271 6.1. multipleOf 273 The value of "multipleOf" MUST be a number, strictly greater than 0. 275 A numeric instance is valid only if division by this keyword's value 276 results in an integer. 278 6.2. maximum 280 The value of "maximum" MUST be a number, representing an inclusive 281 upper limit for a numeric instance. 283 If the instance is a number, then this keyword validates only if the 284 instance is less than or exactly equal to "maximum". 286 6.3. exclusiveMaximum 288 The value of "exclusiveMaximum" MUST be number, representing an 289 exclusive upper limit for a numeric instance. 291 If the instance is a number, then the instance is valid only if it 292 has a value strictly less than (not equal to) "exclusiveMaximum". 294 6.4. minimum 296 The value of "minimum" MUST be a number, representing an inclusive 297 upper limit for a numeric instance. 299 If the instance is a number, then this keyword validates only if the 300 instance is greater than or exactly equal to "minimum". 302 6.5. exclusiveMinimum 304 The value of "exclusiveMinimum" MUST be number, representing an 305 exclusive upper limit for a numeric instance. 307 If the instance is a number, then the instance is valid only if it 308 has a value strictly greater than (not equal to) "exclusiveMinimum". 310 6.6. maxLength 312 The value of this keyword MUST be a non-negative integer. 314 A string instance is valid against this keyword if its length is less 315 than, or equal to, the value of this keyword. 317 The length of a string instance is defined as the number of its 318 characters as defined by RFC 7159 [RFC7159]. 320 6.7. minLength 322 The value of this keyword MUST be a non-negative integer. 324 A string instance is valid against this keyword if its length is 325 greater than, or equal to, the value of this keyword. 327 The length of a string instance is defined as the number of its 328 characters as defined by RFC 7159 [RFC7159]. 330 Omitting this keyword has the same behavior as a value of 0. 332 6.8. pattern 334 The value of this keyword MUST be a string. This string SHOULD be a 335 valid regular expression, according to the ECMA 262 regular 336 expression dialect. 338 A string instance is considered valid if the regular expression 339 matches the instance successfully. Recall: regular expressions are 340 not implicitly anchored. 342 6.9. items 344 The value of "items" MUST be either a valid JSON Schema or an array 345 of valid JSON Schemas. 347 This keyword determines how child instances validate for arrays, and 348 does not directly validate the immediate instance itself. 350 If "items" is a schema, validation succeeds if all elements in the 351 array successfully validate against that schema. 353 If "items" is an array of schemas, validation succeeds if each 354 element of the instance validates against the schema at the same 355 position, if any. 357 Omitting this keyword has the same behavior as an empty schema. 359 6.10. additionalItems 361 The value of "additionalItems" MUST be a valid JSON Schema. 363 This keyword determines how child instances validate for arrays, and 364 does not directly validate the immediate instance itself. 366 If "items" is an array of schemas, validation succeeds if every 367 instance element at a position greater than the size of "items" 368 validates against "additionalItems". 370 Otherwise, "additionalItems" MUST be ignored, as the "items" schema 371 (possibly the default value of an empty schema) is applied to all 372 elements. 374 Omitting this keyword has the same behavior as an empty schema. 376 6.11. maxItems 378 The value of this keyword MUST be a non-negative integer. 380 An array instance is valid against "maxItems" if its size is less 381 than, or equal to, the value of this keyword. 383 6.12. minItems 385 The value of this keyword MUST be a non-negative integer. 387 An array instance is valid against "minItems" if its size is greater 388 than, or equal to, the value of this keyword. 390 Omitting this keyword has the same behavior as a value of 0. 392 6.13. uniqueItems 394 The value of this keyword MUST be a boolean. 396 If this keyword has boolean value false, the instance validates 397 successfully. If it has boolean value true, the instance validates 398 successfully if all of its elements are unique. 400 Omitting this keyword has the same behavior as a value of false. 402 6.14. contains 404 The value of this keyword MUST be a valid JSON Schema. 406 An array instance is valid against "contains" if at least one of its 407 elements is valid against the given schema. 409 6.15. maxProperties 411 The value of this keyword MUST be a non-negative integer. 413 An object instance is valid against "maxProperties" if its number of 414 properties is less than, or equal to, the value of this keyword. 416 6.16. minProperties 418 The value of this keyword MUST be a non-negative integer. 420 An object instance is valid against "minProperties" if its number of 421 properties is greater than, or equal to, the value of this keyword. 423 Omitting this keyword has the same behavior as a value of 0. 425 6.17. required 427 The value of this keyword MUST be an array. Elements of this array, 428 if any, MUST be strings, and MUST be unique. 430 An object instance is valid against this keyword if every item in the 431 array is the name of a property in the instance. 433 Omitting this keyword has the same behavior as an empty array. 435 6.18. properties 437 The value of "properties" MUST be an object. Each value of this 438 object MUST be a valid JSON Schema. 440 This keyword determines how child instances validate for objects, and 441 does not directly validate the immediate instance itself. 443 Validation succeeds if, for each name that appears in both the 444 instance and as a name within this keyword's value, the child 445 instance for that name successfully validates against the 446 corresponding schema. 448 Omitting this keyword has the same behavior as an empty object. 450 6.19. patternProperties 452 The value of "patternProperties" MUST be an object. Each property 453 name of this object SHOULD be a valid regular expression, according 454 to the ECMA 262 regular expression dialect. Each property value of 455 this object MUST be a valid JSON Schema. 457 This keyword determines how child instances validate for objects, and 458 does not directly validate the immediate instance itself. Validation 459 of the primitive instance type against this keyword always succeeds. 461 Validation succeeds if, for each instance name that matches any 462 regular expressions that appear as a property name in this keyword's 463 value, the child instance for that name successfully validates 464 against each schema that corresponds to a matching regular 465 expression. 467 Omitting this keyword has the same behavior as an empty object. 469 6.20. additionalProperties 471 The value of "additionalProperties" MUST be a valid JSON Schema. 473 This keyword determines how child instances validate for objects, and 474 does not directly validate the immediate instance itself. 476 Validation with "additionalProperties" applies only to the child 477 values of instance names that do not match any names in "properties", 478 and do not match any regular expression in "patternProperties". 480 For all such properties, validation succeeds if the child instance 481 validates against the "additionalProperties" schema. 483 Omitting this keyword has the same behavior as an empty schema. 485 6.21. dependencies 487 This keyword specifies rules that are evaluated if the instance is an 488 object and contains a certain property. 490 This keyword's value MUST be an object. Each property specifies a 491 dependency. Each dependency value MUST be an array or a valid JSON 492 Schema. 494 If the dependency value is a subschema, and the dependency key is a 495 property in the instance, the entire instance must validate against 496 the dependency value. 498 If the dependency value is an array, each element in the array, if 499 any, MUST be a string, and MUST be unique. If the dependency key is 500 a property in the instance, each of the items in the dependency value 501 must be a property that exists in the instance. 503 Omitting this keyword has the same behavior as an empty object. 505 6.22. propertyNames 507 The value of "propertyNames" MUST be a valid JSON Schema. 509 If the instance is an object, this keyword validates if every 510 property name in the instance validates against the provided schema. 511 Note the property name that the schema is testing will always be a 512 string. 514 Omitting this keyword has the same behavior as an empty schema. 516 6.23. enum 518 The value of this keyword MUST be an array. This array SHOULD have 519 at least one element. Elements in the array SHOULD be unique. 521 An instance validates successfully against this keyword if its value 522 is equal to one of the elements in this keyword's array value. 524 Elements in the array might be of any value, including null. 526 6.24. const 528 The value of this keyword MAY be of any type, including null. 530 An instance validates successfully against this keyword if its value 531 is equal to the value of the keyword. 533 6.25. type 535 The value of this keyword MUST be either a string or an array. If it 536 is an array, elements of the array MUST be strings and MUST be 537 unique. 539 String values MUST be one of the six primitive types ("null", 540 "boolean", "object", "array", "number", or "string"), or "integer" 541 which matches any number with a zero fractional part. 543 An instance validates if and only if the instance is in any of the 544 sets listed for this keyword. 546 6.26. allOf 548 This keyword's value MUST be a non-empty array. Each item of the 549 array MUST be a valid JSON Schema. 551 An instance validates successfully against this keyword if it 552 validates successfully against all schemas defined by this keyword's 553 value. 555 6.27. anyOf 557 This keyword's value MUST be a non-empty array. Each item of the 558 array MUST be a valid JSON Schema. 560 An instance validates successfully against this keyword if it 561 validates successfully against at least one schema defined by this 562 keyword's value. 564 6.28. oneOf 566 This keyword's value MUST be a non-empty array. Each item of the 567 array MUST be a valid JSON Schema. 569 An instance validates successfully against this keyword if it 570 validates successfully against exactly one schema defined by this 571 keyword's value. 573 6.29. not 575 This keyword's value MUST be a valid JSON Schema. 577 An instance is valid against this keyword if it fails to validate 578 successfully against the schema defined by this keyword. 580 7. Metadata keywords 582 7.1. definitions 584 This keyword's value MUST be an object. Each member value of this 585 object MUST be a valid JSON Schema. 587 This keyword plays no role in validation per se. Its role is to 588 provide a standardized location for schema authors to inline JSON 589 Schemas into a more general schema. 591 As an example, here is a schema describing an array of positive 592 integers, where the positive integer constraint is a subschema in 593 "definitions": 595 { 596 "type": "array", 597 "items": { "$ref": "#/definitions/positiveInteger" }, 598 "definitions": { 599 "positiveInteger": { 600 "type": "integer", 601 "exclusiveMinimum": 0 602 } 603 } 604 } 606 7.2. "title" and "description" 608 The value of both of these keywords MUST be a string. 610 Both of these keywords can be used to decorate a user interface with 611 information about the data produced by this user interface. A title 612 will preferably be short, whereas a description will provide 613 explanation about the purpose of the instance described by this 614 schema. 616 7.3. "default" 618 There are no restrictions placed on the value of this keyword. 620 This keyword can be used to supply a default JSON value associated 621 with a particular schema. It is RECOMMENDED that a default value be 622 valid against the associated schema. 624 7.4. "examples" 626 The value of this keyword MUST be an array. There are no 627 restrictions placed on the values within the array. 629 This keyword can be used to provide sample JSON values associated 630 with a particular schema, for the purpose of illustrating usage. It 631 is RECOMMENDED that these values be valid against the associated 632 schema. 634 Implementations MAY use the value of "default", if present, as an 635 additional example. If "examples" is absent, "default" MAY still be 636 used in this manner. 638 8. Semantic validation with "format" 640 8.1. Foreword 642 Structural validation alone may be insufficient to validate that an 643 instance meets all the requirements of an application. The "format" 644 keyword is defined to allow interoperable semantic validation for a 645 fixed subset of values which are accurately described by 646 authoritative resources, be they RFCs or other external 647 specifications. 649 The value of this keyword is called a format attribute. It MUST be a 650 string. A format attribute can generally only validate a given set 651 of instance types. If the type of the instance to validate is not in 652 this set, validation for this format attribute and instance SHOULD 653 succeed. 655 8.2. Implementation requirements 657 Implementations MAY support the "format" keyword. Should they choose 658 to do so: 660 they SHOULD implement validation for attributes defined below; 662 they SHOULD offer an option to disable validation for this 663 keyword. 665 Implementations MAY add custom format attributes. Save for agreement 666 between parties, schema authors SHALL NOT expect a peer 667 implementation to support this keyword and/or custom format 668 attributes. 670 8.3. Defined formats 672 8.3.1. date-time 674 This attribute applies to string instances. 676 A string instance is valid against this attribute if it is a valid 677 date representation as defined by RFC 3339, section 5.6 [RFC3339]. 679 8.3.2. email 681 This attribute applies to string instances. 683 A string instance is valid against this attribute if it is a valid 684 Internet email address as defined by RFC 5322, section 3.4.1 685 [RFC5322]. 687 8.3.3. hostname 689 This attribute applies to string instances. 691 A string instance is valid against this attribute if it is a valid 692 representation for an Internet host name, as defined by RFC 1034, 693 section 3.1 [RFC1034]. 695 8.3.4. ipv4 697 This attribute applies to string instances. 699 A string instance is valid against this attribute if it is a valid 700 representation of an IPv4 address according to the "dotted-quad" ABNF 701 syntax as defined in RFC 2673, section 3.2 [RFC2673]. 703 8.3.5. ipv6 705 This attribute applies to string instances. 707 A string instance is valid against this attribute if it is a valid 708 representation of an IPv6 address as defined in RFC 2373, section 2.2 709 [RFC2373]. 711 8.3.6. uri 713 This attribute applies to string instances. 715 A string instance is valid against this attribute if it is a valid 716 URI, according to [RFC3986]. 718 8.3.7. uri-reference 720 This attribute applies to string instances. 722 A string instance is valid against this attribute if it is a valid 723 URI Reference (either a URI or a relative-reference), according to 724 [RFC3986]. 726 8.3.8. uri-template 728 This attribute applies to string instances. 730 A string instance is valid against this attribute if it is a valid 731 URI Template (of any level), according to [RFC6570]. 733 8.3.9. json-pointer 735 This attribute applies to string instances. 737 A string instance is valid against this attribute if it is a valid 738 JSON Pointer, according to [RFC6901] 740 9. Security considerations 742 JSON Schema validation defines a vocabulary for JSON Schema core and 743 concerns all the security considerations listed there. 745 JSON Schema validation allows the use of Regular Expressions, which 746 have numerous different (often incompatible) implementations. Some 747 implementations allow the embedding of arbitrary code, which is 748 outside the scope of JSON Schema and MUST NOT be permitted. Regular 749 expressions can often also be crafted to be extremely expensive to 750 compute (with so-called "catastrophic backtracking"), resulting in a 751 denial-of-service attack. 753 10. References 755 10.1. Normative References 757 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 758 Requirement Levels", BCP 14, RFC 2119, 759 DOI 10.17487/RFC2119, March 1997, 760 . 762 [json-schema] 763 "JSON Schema: A Media Type for Describing JSON Documents", 764 draft-wright-json-schema-00 (work in progress), October 765 2016. 767 10.2. Informative References 769 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 770 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 771 . 773 [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing 774 Architecture", RFC 2373, DOI 10.17487/RFC2373, July 1998, 775 . 777 [RFC2673] Crawford, M., "Binary Labels in the Domain Name System", 778 RFC 2673, DOI 10.17487/RFC2673, August 1999, 779 . 781 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 782 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 783 . 785 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 786 Resource Identifier (URI): Generic Syntax", STD 66, 787 RFC 3986, DOI 10.17487/RFC3986, January 2005, 788 . 790 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 791 and D. Orchard, "URI Template", RFC 6570, 792 DOI 10.17487/RFC6570, March 2012, 793 . 795 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 796 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 797 DOI 10.17487/RFC6901, April 2013, 798 . 800 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 801 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 802 2014, . 804 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 805 DOI 10.17487/RFC5322, October 2008, 806 . 808 [ecma262] "ECMA 262 specification", . 812 Appendix A. Acknowledgments 814 Thanks to Gary Court, Francis Galiegue, Kris Zyp, and Geraint Luff 815 for their work on the initial drafts of JSON Schema. 817 Thanks to Jason Desrosiers, Daniel Perrett, Erik Wilde, Ben Hutton, 818 Evgeny Poberezkin, Brad Bowman, Gowry Sankar, Donald Pipowitch, and 819 Dave Finlay for their submissions and patches to the document. 821 Appendix B. ChangeLog 823 [[CREF1: This section to be removed before leaving Internet-Draft 824 status.]] 826 draft-wright-json-schema-validation-01 828 * Standardized on hyphenated format names ("uriref" becomes "uri- 829 ref") 831 * Add the formats "uri-template" and "json-pointer" 833 * Changed "exclusiveMaximum"/"exclusiveMinimum" from boolean 834 modifiers of "maximum"/"minimum" to independent numeric fields. 836 * Split the additionalItems/items into two sections 838 * Reworked properties/patternProperties/additionalProperties 839 definition 841 * Added "examples" keyword 843 * Added "contains" keyword 845 * Allow empty "required" and "dependencies" arrays 847 * Fixed "type" reference to primitive types 849 * Added "const" keyword 851 * Added "propertyNames" keyword 853 draft-wright-json-schema-validation-00 855 * Added additional security considerations 857 * Removed reference to "latest version" meta-schema, use numbered 858 version instead 860 * Rephrased many keyword definitions for brevity 862 * Added "uriref" format that also allows relative URI references 864 draft-fge-json-schema-validation-01 866 * Initial draft. 868 * Salvaged from draft v3. 870 * Redefine the "required" keyword. 872 * Remove "extends", "disallow" 874 * Add "anyOf", "allOf", "oneOf", "not", "definitions", 875 "minProperties", "maxProperties". 877 * "dependencies" member values can no longer be single strings; 878 at least one element is required in a property dependency 879 array. 881 * Rename "divisibleBy" to "multipleOf". 883 * "type" arrays can no longer have schemas; remove "any" as a 884 possible value. 886 * Rework the "format" section; make support optional. 888 * "format": remove attributes "phone", "style", "color"; rename 889 "ip-address" to "ipv4"; add references for all attributes. 891 * Provide algorithms to calculate schema(s) for array/object 892 instances. 894 * Add interoperability considerations. 896 Authors' Addresses 898 Austin Wright (editor) 900 EMail: aaa@bzfx.net 902 Geraint Luff 904 EMail: luffgd@gmail.com 905 Henry Andrews (editor) 906 Cloudflare, Inc. 908 EMail: henry@cloudflare.com