idnits 2.17.1 draft-json-schema-language-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 28, 2019) is 1818 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JSON Working Group U. Carion 3 Internet-Draft April 28, 2019 4 Intended status: Standards Track 5 Expires: October 30, 2019 7 JSON Schema Language 8 draft-json-schema-language-00 10 Abstract 12 JavaScript Object Notation (JSON) Schema Language is a portable 13 method for describing the format of JSON data and the errors 14 associated with ill-formed data. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on October 30, 2019. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . 3 55 4.2. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4.3. Additional restrictions to prevent ambiguity . . . . . . 5 57 4.4. Evaluation context and reference resolution . . . . . . . 6 58 5. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 5.1. Configuration . . . . . . . . . . . . . . . . . . . . . . 8 60 5.1.1. Strict schema semantics . . . . . . . . . . . . . . . 8 61 5.1.2. Strict instance semantics . . . . . . . . . . . . . . 8 62 5.2. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 5.3. Evaluation . . . . . . . . . . . . . . . . . . . . . . . 9 64 5.3.1. Empty form . . . . . . . . . . . . . . . . . . . . . 9 65 5.3.2. Ref form . . . . . . . . . . . . . . . . . . . . . . 9 66 5.3.3. Type form . . . . . . . . . . . . . . . . . . . . . . 10 67 5.3.4. Elements form . . . . . . . . . . . . . . . . . . . . 11 68 5.3.5. Properties form . . . . . . . . . . . . . . . . . . . 12 69 5.3.6. Values form . . . . . . . . . . . . . . . . . . . . . 14 70 5.3.7. Discriminator form . . . . . . . . . . . . . . . . . 15 71 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 73 8. Normative References . . . . . . . . . . . . . . . . . . . . 19 74 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 19 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 77 1. Introduction 79 JSON Schema Language is a schema language for JSON data. This 80 document specifies: 82 o When a JSON object is a correct JSON Schema Language schema 84 o When a JSON document is valid with respect to a correct JSON 85 Schema Language schema 87 o A standardized form of errors to produce when validating a JSON 88 value 90 JSON Schema Language is centered around the question of validating a 91 JSON value (an "instance") against a JSON object (a "schema"), within 92 the context of a collection of other schemas (an "evaluation 93 context"). 95 2. Conventions 97 The keywords *MUST*, *MUST NOT*, *REQUIRED*, *SHALL*, *SHALL NOT*, 98 *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *MAY*, and *OPTIONAL*, when 99 they appear in this document, are to be interpreted as described in 100 [RFC2119]. 102 The terms "absolute-URI" and "URI-reference", when they appear in 103 this document, are to be understood as they are defined in [RFC3986]. 105 The term "JSON Pointer", when it appears in this document, is to be 106 understood as it is defined in [RFC6901]. 108 3. Terminology 110 o instance: A JSON value being validated. 112 o schema: A JSON object describing the form of valid instances. 114 o evaluation context: A collection of schemas which may refer to one 115 another. 117 o validation error: A JSON object representing a reason why an 118 instance is invalid. 120 4. Syntax 122 This section specifies when a JSON document is a correct schema. 124 4.1. Keywords 126 Some member names of a schema are reserved, and carry special 127 meaning. These member names are called keywords. Correct schemas 128 *MUST* satisfy the following requirements: 130 o "id": If a schema has a member named "id", its corresponding value 131 *MUST* be a JSON string encoding an absolute-URI. 133 o "definitions": If a schema has a member named "definitions", its 134 corresponding value *MUST* be a JSON object. The values of this 135 object *MUST* all be correct schemas. 137 o "ref": If a schema has a member named "ref", its corresponding 138 value *MUST* be a JSON string encoding a URI-reference. 140 o "type": If a schema has a member named "type", its corresponding 141 value *MUST* be a JSON string encoding one of the values "null", 142 "boolean", "number", or "string". 144 o "elements": If a schema has a member named "elements", its 145 corresponding value *MUST* be a JSON object. This object *MUST* 146 be a correct schema. 148 o "properties": If a schema has a member named "properties", its 149 corresponding value *MUST* be a JSON object. The values of this 150 object *MUST* all be correct schemas. 152 o "optionalProperties": If a schema has a member named 153 "optionalProperties", its corresponding value *MUST* be a JSON 154 object. The values of this object *MUST* all be correct schemas. 156 o "values": If a schema has a member named "values", its 157 corresponding value *MUST* be a JSON object. This object *MUST* 158 be a correct schema. 160 o "discriminator": If a schema has a member named "discriminator", 161 its corresponding value *MUST* be a JSON object. This object 162 *MUST* have exactly two members: 164 * A member with the name "tag", whose corresponding value *MUST* 165 be a JSON string. 167 * A member with the name "mapping", whose corresponding value 168 *MUST* be a JSON object. The values of this object *MUST* all 169 be correct schemas. 171 4.2. Forms 173 Only certain combinations of schema keywords are correct. These 174 valid combinations are called "forms". Correct schemas *MUST* fall 175 into exactly one of the following forms: 177 o The "empty" form: the schema may have members with the name "id" 178 and/or "definitions", but none of the other keywords listed in 179 Section 4.1. 181 o The "ref" form: the schema may have members with the name "id", 182 "definitions", and/or "ref", but none of the other keywords listed 183 in Section 4.1. 185 o The "type" form: the schema may have members with the name "id", 186 "definitions", and/or "type", but none of the other keywords 187 listed in Section 4.1. 189 o The "elements" form: the schema may have members with the name 190 "id", "definitions", and/or "elements", but none of the other 191 keywords listed in Section 4.1. 193 o The "properties" form: the schema may have members with the name 194 "id", "definitions", "properties", and/or "optionalProperties", 195 but none of the other keywords listed in Section 4.1. 197 o The "values" form: the schema may have members with the name "id", 198 "definitions", and/or "values", but none of the other keywords 199 listed in Section 4.1. 201 o The "discriminator" form: the schema may have members with the 202 name "id", "definitions", and/or "discriminator", but none of the 203 other keywords listed in Section 4.1. 205 4.3. Additional restrictions to prevent ambiguity 207 To prevent ambiguous or unsatisfiable schemas during evaluation (see 208 Section 5.3), there are two additional constraints that all JSON 209 documents must satisfy to be a valid schema: 211 1. If a schema both "properties" and "optionalProperties" members, 212 the "properties" and "optionalProperties" values *MUST NOT* share 213 any member names in common. 215 Without this restriction, it could be ambiguous whether a 216 property is required or not. 218 2. If a schema has a "discriminator" member, all of the values of 219 "mapping" within "discriminator" *MUST* be of the "properties" 220 form described in Section 4.2. Furthermore, these schemas within 221 "mapping" *MUST NOT* have a member in "properties" or 222 "optionalProperties" whose name equals that of "tag"'s within 223 "discriminator". 225 Without this restriction, it could be possible for a schema to 226 require that an instance be simultaneously an object and not an 227 object. Additionally, schemas might also give contradictory 228 requirements by describing the same instance member through both 229 "tag" and "properties". 231 To illustrate the first restriction, the following JSON document is 232 not a valid schema, as "foo" appears both in "properties" and 233 "optionalProperties": 235 { 236 "properties": { "foo": {} }, 237 "optionalProperties": { "foo": {} } 238 } 239 To illsturate the second restriction, the following JSON document is 240 not a valid schema because one of the members of "mapping" is not of 241 the "properties" form: 243 { 244 "discriminator": { 245 "tag": "foo", 246 "mapping": { 247 "a": { "elements": {} } 248 } 249 } 250 } 252 Finally, the following JSON document is not a valid schema because 253 one of the members of "mapping" has a "properties" member whose value 254 equals that of "tag"'s: 256 { 257 "discriminator": { 258 "tag": "foo", 259 "mapping": { 260 "a": { "properties": { "foo": { "type": "number" } } } 261 } 262 } 263 } 265 4.4. Evaluation context and reference resolution 267 An evaluation context is a collection of schemas which may refer to 268 one another. An evaluation context is correct if: 270 o All of its constituent schemas are correct, 272 o No two constituent schemas have the same "id" value, and 274 o No more than one schema lacks an "id" value. 276 If a schema is correct and it has a member named "ref", then this 277 member is said to be a reference. The reference of a correct schema 278 *MUST* be resolvable. Reference resolution is defined as follows: 280 1. By Section 4.1, a schema may be contained by another schema. 281 Reference resolution uses the "root" of a schema to determine a 282 base URI. The "root" of a given schema is the immediate element 283 of an evaluation context which contains the given schema. All 284 schemas are, for this definition, considered to contain 285 themselves. 287 2. By Section 4.1, the value of the reference must be a URI- 288 reference. This URI-reference is resolved using the process 289 described in [RFC3986] to produce a resolved URI. If the root of 290 a schema has a member named "id", then that member's 291 corresponding value shall be used as the base URI for the URI 292 resolution process; otherwise, no base URI is used. 294 If the URI-reference cannot be resolved, then the reference is 295 unresolvable. 297 3. Take the URI from (2), and remove its fragment part, if present. 299 4. Find the element of the evaluation context which has a member 300 named "id" and whose value equals the URI from (3). If there 301 does not exist such a schema, then the reference is unresolvable. 303 5. If URI from (2) has no fragment, then the reference resolves to 304 the schema from (4). 306 6. Otherwise, the schema from (4) must have a member named 307 "definitions"; if it does not, then the reference is 308 unresolvable. Furthermore, the "definitions" value must have a 309 member whose name equals the fragment of the URI from (2); if it 310 does not, then the reference is unresolvable. If it does have 311 such a member, then the reference resolves to this member's 312 value. 314 For example, if an evaluation context contains two schemas: 316 { 317 "id": "http://example.com", 318 "ref": "/foo#a" 319 } 321 { 322 "id": "http://example.com/foo", 323 "definitions": { 324 "a": { 325 "ref": "#" 326 }, 327 "b": { 328 "id": "http://example.com/bar", 329 "ref": "#" 330 } 331 } 332 } 333 Then the reference with value "/foo#a" refers to the "a" definition 334 of the schema with ID "http://example.com/foo". Both of the 335 references with value "#" refer the root schema with ID 336 "http://example.com/foo". The "id" keyword of the "b" definition is 337 irrelevant, as it occurs outside of a root schema. 339 5. Semantics 341 This section specifies when an instance is valid against a correct 342 schema, within the context of an evaluation context. This section 343 also specifies a standardized form of errors to produce when 344 validating an instance. 346 5.1. Configuration 348 Users will have different desired behavior with respect to 349 unspecified members in a schema or instance. Two distinct sets of 350 semantics (one for schemas, another for instances), determine whether 351 unspecified members are acceptable. 353 5.1.1. Strict schema semantics 355 When evaluation is using strict schema semantics, then a correct 356 schema *MUST NOT* contain members whose names are outside the list of 357 keywords described in Section 4.1. When evaluation is not using 358 strict schema semantics, then a correct schema *MAY* contain members 359 whose names are outside this list. 361 Implementations *MAY* allow users to choose whether to use strict 362 schema semantics. Implementations *SHOULD* document whether they use 363 strict schema semantics by default. 365 5.1.2. Strict instance semantics 367 See Section 5.3.5 for how strict instance semantics affects whether 368 an instance is valid with respect to a schema. 370 Implementations *MAY* allow users to choose whether to use strict 371 instance semantics. Implementations *SHOULD* document whether they 372 use strict instance semantics by default. 374 5.2. Errors 376 To facilitate consistent validation error handling, this document 377 specifies a standard error format. Implementations *SHOULD* support 378 producing errors in this standard form. 380 The standard error format is a JSON array. The order of the elements 381 of this array is not specified. The elements of this array are JSON 382 objects with up to three members: 384 o A member with the name "instancePath", whose value is a JSON 385 string containing a JSON Pointer. This JSON Pointer will point to 386 the part of the instance that was rejected. 388 o A member with the name "schemaPath", whose value is a JSON string 389 containing a JSON Pointer. This JSON Pointer will point to the 390 part of the schema that rejected the instance. 392 o A member with the name "schemaURI", whose value is an absolute- 393 URI. This URI will be the "id" value of the root schema of the 394 schema that rejected the instance. See Section 4.4 for a 395 definition of a schema's root. If the root schema lacks an "id" 396 value, then the "schemaURI" member shall be omitted. 398 The values for "instancePath" and "schemaPath" depend on the form of 399 the schema, and are described in detail in Section 5.3. 401 5.3. Evaluation 403 Whether an instance is valid against a schema depends upon the form 404 of the schema. This section describes how each form validates 405 instances. 407 5.3.1. Empty form 409 If a schema is of the "empty" form, then it accepts all instances. 411 5.3.2. Ref form 413 The "ref" form is meant to enable schema re-use. 415 If a schema is of the "ref" form, then it accepts an instance if and 416 only if the schema which the "ref" member resolves to accepts the 417 instance. The standard errors to produce are the same as those that 418 the referent schema produces. The resolution of a "ref" member is 419 described in Section 4.4. 421 For example, if we evaluate the instance: 423 "example" 425 Against the schema: 427 { 428 "ref": "http://example.com" 429 } 431 Within an evaluating context containing the schema: 433 { 434 "id": "http://example.com", 435 "type": "number" 436 } 438 Then the standard errors are: 440 [ 441 { 442 "instancePath": "", 443 "schemaPath": "/type", 444 "schemaURI": "http://example.com" 445 } 446 ] 448 See Section 5.3.3 for how the "type" member produces errors, as the 449 errors in the example above compose upon "type" errors. 451 5.3.3. Type form 453 The "type" form is meant to describe the primitive data types of 454 JSON. 456 If a schema is of the "type" form, then: 458 o If the value of the "type" member is "null", then the instance is 459 accepted if it equals "null". 461 o If the value of the "type" member is "boolean", then the instance 462 is accepted if it equals "true" or "false". 464 o If the value of the "type" member is "number", then the instance 465 is accepted if it is a JSON number. 467 o If the value of the "type" member is "string", then the instance 468 is accepted if it is a JSON string. 470 If the instance is not accepted, then the standard error for this 471 case shall have an "instancePath" pointing to the instance, and a 472 "schemaPath" pointing to the "type" member. 474 For example, if we evaluate the instance: 476 "example" 478 Against the schema: 480 { "type": "number" } 482 Then the standard errors are: 484 [{ "instancePath": "", "schemaPath": "/type" }] 486 5.3.4. Elements form 488 The "elements" form is meant to describe JSON arrays representing 489 homogeneous data. When a schema is of the "elements" form, it 490 validates: 492 o That the instance is an array, and 494 o That all of the elements of the array are of the same type. 496 If a schema is of the "elements" form, then: 498 1. If the instance is not a JSON array, then the instance is 499 rejected. The standard error shall have an "instancePath" 500 pointing to the instance, and a "schemaPath" pointing to the 501 "elements" member. 503 2. Otherwise, the instance is accepted if each element of the 504 instance is accepted by the value of the "elements" member. The 505 standard error shall be the concatenation of the standard errors 506 from evaluating each element of the instance against the value of 507 the "elements" member. 509 For example, if we have the schema: 511 { 512 "elements": { 513 "type": "number" 514 } 515 } 517 Then if we evaluate the instance: 519 "example" 521 Against this schema, the standard errors are: 523 [{ "instancePath": "", "schemaPath": "/elements" }] 524 If instead we evaluate the instance: 526 [1, 2, "foo", 3, "bar"] 528 The standard errors are: 530 [ 531 { "instancePath": "/2", "schemaPath": "/elements/type" }, 532 { "instancePath": "/4", "schemaPath": "/elements/type" } 533 ] 535 5.3.5. Properties form 537 The "properties" form is meant to describe JSON objects being used in 538 a fashion similar to structs in C-like languages. When a schema is 539 of the "properties" form, it validates: 541 o That the instance is an object, 543 o That the instance has a set of required properties, each 544 satisfying their own respective schema, and 546 o That the instance may have a set of optional properties that, if 547 present in the instance, satisfy their own respective schema. 549 If a schema is of the "properties" form, then: 551 1. If the instance is not a JSON object, then the instance is 552 rejected. 554 The standard error for this case has an "instancePath" pointing 555 to the instance. If the schema has a "properties" member, then 556 the "schemaPath" of the error shall point to the "properties" 557 member. Otherwise, "schemaPath" shall point to the 558 "optionalProperties" member. 560 2. If the instance is a JSON object, and the schema has a 561 "properties" member, then for each member name of the 562 "properties" of the schema, a member of the same name must appear 563 in the instance. Otherwise, the instance is rejected. 565 The standard error for this case has an "instancePath" pointing 566 to the instance, and a "schemaPath" pointing to the member of 567 "properties" whose name lacks a counterpart in the instance. 569 3. If the instance is a JSON object, then for each member of the 570 instance, find a member of the same name in the "properties" or 571 "optionalProperties" of the schema. 573 * If no such member in the "properties" or "optionalProperties" 574 exists, and validation is using strict instance semantics, 575 then the instance is rejected. 577 The standard error for this case has an "instancePath" 578 pointing to the member of the instance lacking a counterpart 579 in the schema, and a "schemaPath" pointing to the schema. 581 * If such a member in the "properties" or "optionalProperties" 582 does exist, then the value of the member from the instance 583 must be accepted by the value of the corresponding member from 584 the schema. Otherwise, the instance is rejected. 586 The standard error for this case is the concatenation of the 587 errors from evaluating the member of the instance against the 588 member of the schema. 590 An instance may have errors arising from both (2) and (3). In this 591 case, the standard errors should be concatenated together. 593 For example, if we have the schema: 595 { 596 "properties": { 597 "a": { "type": "string" }, 598 "b": { "type": "string" } 599 }, 600 "optionalProperties": { 601 "c": { "type": "string" }, 602 "d": { "type": "string" } 603 } 604 } 606 Then if we evaluate the instance: 608 "example" 610 Against this schema, then the standard errors are: 612 [{ "instancePath": "", "schemaPath": "/properties" }] 614 If instead we evalute the instance: 616 { "b": 3, "c": 3, "e": 3 } 618 The standard errors, using strict instance semantics, are: 620 [ 621 { "instancePath": "", 622 "schemaPath": "/properties/a" }, 623 { "instancePath": "/b", 624 "schemaPath": "/properties/b/type" }, 625 { "instancePath": "/c", 626 "schemaPath": "/optionalProperties/c/type" }, 627 { "instancePath": "/e", 628 "schemaPath": "" } 629 ] 631 If we the same instance were evaluated, but without strict instance 632 semantics, the final element of the above array of errors would not 633 be present. 635 5.3.6. Values form 637 The "values" form is meant to describe JSON objects being used as an 638 associative array mapping arbitrary strings to values all of the same 639 type. When a schema is of the "properties" form, it validates: 641 o That the instance is an object, and 643 o That the values of the instance all satisfy the same schema. 645 If a schema is of the "values" form, then: 647 1. If the instance is not a JSON object, then the instance is 648 rejected. The standard error shall have an "instancePath" 649 pointing to the instance, and a "schemaPath" pointing to the 650 "values" member. 652 2. Otherwise, the instance is accepted if the value of each member 653 of the instance is accepted by the value of the "values" member. 654 The standard error shall be the concatenation of the standard 655 errors from evaluating the value of each member of the instance 656 against the value of the "values" member. 658 For example, if we have the schema: 660 { 661 "values": { 662 "type": "number" 663 } 664 } 666 Then if we evaluate the instance: 668 "example" 670 Against this schema, the standard errors are: 672 [{ "instancePath": "", "schemaPath": "/values" }] 674 If instead we evaluate the instance: 676 { "a": 1, "b": 2, "c": "foo", "d": 3, "e": "bar" } 678 The standard errors are: 680 [ 681 { "instancePath": "/c", "schemaPath": "/values/type" }, 682 { "instancePath": "/e", "schemaPath": "/values/type" } 683 ] 685 5.3.7. Discriminator form 687 The "discriminator" form is meant to describe JSON objects being used 688 in a fashion similar to a discriminated union construct in C-like 689 languages. When a schema is of the "disciminator" type, it 690 validates: 692 o That the instance is an object, 694 o That the instance has a particular "disciminator" property, 696 o That this "discriminator" value is a string within a set of valid 697 values, and 699 o That the instance satisfies another schema, where this other 700 schema is chosen based on the value of the "discriminator" 701 property. 703 If a schema is of the "disciminator" form, then: 705 1. If the instance is not a JSON object, then the instance is 706 rejected. The standard error shall have an "instancePath" 707 pointing to the instance, and a "schemaPath" pointing to the 708 "discriminator" member. 710 2. If the instance is a JSON object and lacks a member whose name 711 equals the "tag" value of the "discriminator" of the schema, then 712 the instance is rejected. 714 The standard error to produce in this case has an "instancePath" 715 pointing to the instance, and a "schemaPath" pointing to the 716 "tag" member of the "disciminator" member of the schema. 718 3. If the instance is a JSON object and has a member whose name 719 equals the "tag" value of the "discriminator" of the schema, but 720 that member's value is not a string, then the instance is 721 rejected. 723 The standard error to produce in this case has an "instancePath" 724 pointing to the member of the instance corresponding to "tag", 725 and a "schemaPath" pointing to the "tag" member of the 726 discriminator. 728 4. If the instance is a JSON object and has a member whose name 729 equals the "tag" value of the "discriminator" of the schema and 730 whose value is a string, but that member's value is not equal to 731 any of the member names in the "mapping" of the "discriminator", 732 then the instance is rejected. 734 The standard error to produce in this case has an "instancePath" 735 pointing to the member of the instance corresponding to "tag", 736 and a "schemaPath" pointing to the "mapping" member of the 737 "discriminator" member of the schema. 739 5. If the instance is a JSON object and has a member whose name 740 equals the "tag" value of the "discriminator" of the schema, and 741 that member's value is equal to one of the member names in the 742 "mapping" of the "discriminator", then the instance must satisfy 743 this corresponding schema in "mapping". Otherwise, the instance 744 is rejected. 746 The standard errors to produce in this case are those produced by 747 evaluating the instance against the schema within the "mapping". 749 For example, if we have the schema: 751 { 752 "discriminator": { 753 "tag": "version", 754 "mapping": { 755 "v1": { 756 "properties": { 757 "a": { "type": "number" } 758 } 759 }, 760 "v2": { 761 "properties": { 762 "a": { "type": "string" } 763 } 764 } 765 } 766 } 767 } 769 Then if we evaluate the instance: 771 "example" 773 Against this schema, the standard errors are: 775 [{ "instancePath": "", "schemaPath": "/discriminator" }] 777 If we instead evaluate the instance: 779 {} 781 Then the standard errors are: 783 [{ "instancePath": "", "schemaPath": "/discriminator/tag" }] 785 If we instead evaluate the instance: 787 { "version": 1 } 789 Then the standard errors are: 791 [{ "instancePath": "/version", "schemaPath": "/discriminator/tag" }] 793 If we instead evaluate the instance: 795 { 796 "version": "v3" 797 } 798 Then the standard errors are: 800 [ 801 { "instancePath": "/version", 802 "schemaPath": "/discriminator/mapping" } 803 ] 805 Finally, if the instance evaluated were: 807 { 808 "version": "v2", 809 "a": 3 810 } 812 Then the standard errors are: 814 [ 815 { 816 "instancePath": "/a", 817 "schemaPath": "/discriminator/mapping/v2/properties/a/type" 818 } 819 ] 821 6. IANA Considerations 823 No IANA considerations. 825 7. Security Considerations 827 Implementations of JSON Schema Language will necessarily be 828 manipulating JSON data. Therefore, the security considerations of 829 [RFC8259] are all relevant here. 831 Implementations which evaluate user-inputted schemas *SHOULD* 832 implement mechanisms to detect, and abort, circular references which 833 might cause a naive implementation to go into an infinite loop. 834 Without such mechanisms, implementations may be vulnerable to denial- 835 of-service attacks. 837 Implementations of JSON Schema Language *SHOULD NOT* naively attempt 838 to fetch and evaluate schemas when they are referred to using the 839 "ref" keyword. Doing so could lead to denial of service. Instead, 840 implementations should only fetch schemas through secure channels, 841 and should only fetch and evaluate schemas from trusted sources. 843 8. Normative References 845 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 846 Requirement Levels", BCP 14, RFC 2119, 847 DOI 10.17487/RFC2119, March 1997, 848 . 850 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 851 Resource Identifier (URI): Generic Syntax", STD 66, 852 RFC 3986, DOI 10.17487/RFC3986, January 2005, 853 . 855 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 856 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 857 DOI 10.17487/RFC6901, April 2013, 858 . 860 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 861 Interchange Format", STD 90, RFC 8259, 862 DOI 10.17487/RFC8259, December 2017, 863 . 865 Appendix A. Acknowledgments 867 Thanks to Gary Court, Francis Galiegue, Kris Zyp, Geraint Luff, Jason 868 Desrosiers, Daniel Perrett, Erik Wilde, Ben Hutton, Evgeny 869 Poberezkin, Brad Bowman, Gowry Sankar, Donald Pipowitch, Dave Finlay, 870 Denis Laxalde, Henry Andrews, and Austin Wright for their work on the 871 initial drafts of JSON Schema, which inspired JSON Schema Language. 873 Author's Address 875 Ulysse Carion 877 Email: ulyssecarion@gmail.com