idnits 2.17.00 (12 Aug 2021) /tmp/idnits36188/draft-ietf-appsawg-json-patch-09.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 (January 4, 2013) is 3423 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) == Outdated reference: draft-ietf-appsawg-json-pointer has been published as RFC 6901 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Applications Area Working Group P. Bryan, Ed. 3 Internet-Draft Salesforce.com 4 Intended status: Standards Track M. Nottingham, Ed. 5 Expires: July 8, 2013 Akamai 6 January 4, 2013 8 JSON Patch 9 draft-ietf-appsawg-json-patch-09 11 Abstract 13 JSON Patch defines the media type "application/json-patch", a JSON 14 document structure for expressing a sequence of operations to apply 15 to a JavaScript Object Notation (JSON) document, suitable for use 16 with the HTTP PATCH method. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on July 8, 2013. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. Document Structure . . . . . . . . . . . . . . . . . . . . . . 3 55 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4.1. add . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.2. remove . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 4.3. replace . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 4.4. move . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 4.5. copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 4.6. test . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 8 63 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 64 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 66 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 9.1. Normative References . . . . . . . . . . . . . . . . . . . 10 68 9.2. Informative References . . . . . . . . . . . . . . . . . . 10 69 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10 70 A.1. Adding an Object Member . . . . . . . . . . . . . . . . . 10 71 A.2. Adding an Array Element . . . . . . . . . . . . . . . . . 11 72 A.3. Removing an Object Member . . . . . . . . . . . . . . . . 11 73 A.4. Removing an Array Element . . . . . . . . . . . . . . . . 12 74 A.5. Replacing a Value . . . . . . . . . . . . . . . . . . . . 12 75 A.6. Moving a Value . . . . . . . . . . . . . . . . . . . . . . 12 76 A.7. Moving an Array Element . . . . . . . . . . . . . . . . . 13 77 A.8. Testing a Value: Success . . . . . . . . . . . . . . . . . 14 78 A.9. Testing a Value: Error . . . . . . . . . . . . . . . . . . 14 79 A.10. Adding a nested Member Object . . . . . . . . . . . . . . 14 80 A.11. Ignoring Unrecognized Elements . . . . . . . . . . . . . . 15 81 A.12. Adding to a Non-existant Target . . . . . . . . . . . . . 15 82 A.13. Invalid JSON Patch Document . . . . . . . . . . . . . . . 15 83 A.14. ~ Escape Ordering . . . . . . . . . . . . . . . . . . . . 16 84 A.15. Comparing Strings and Numbers . . . . . . . . . . . . . . 16 85 A.16. Adding an Array Value . . . . . . . . . . . . . . . . . . 17 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 88 1. Introduction 90 JavaScript Object Notation (JSON) [RFC4627] is a common format for 91 the exchange and storage of structured data. HTTP PATCH [RFC5789] 92 extends the Hypertext Transfer Protocol (HTTP) [RFC2616] with a 93 method to perform partial modifications to resources. 95 JSON Patch is a format (identified by the media type "application/ 96 json-patch") for expressing a sequence of operations to apply to a 97 target JSON document, suitable for use with the HTTP PATCH method. 99 This format is also potentially useful in other cases where necessary 100 to make partial updates to a JSON document. 102 2. Conventions 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in RFC 2119 [RFC2119]. 108 See Section 5 for information about handling errors. 110 3. Document Structure 112 A JSON Patch document is a JSON [RFC4627] document that represents an 113 array of objects. Each object represents a single operation to be 114 applied to the target JSON document. 116 An example JSON Patch document: 118 [ 119 { "op": "test", "path": "/a/b/c", "value": "foo" }, 120 { "op": "remove", "path": "/a/b/c" }, 121 { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }, 122 { "op": "replace", "path": "/a/b/c", "value": 42 }, 123 { "op": "move", "from": "/a/b/c", "path": "/a/b/d" }, 124 { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" } 125 ] 127 Evaluation of a JSON Patch document begins against a target JSON 128 document. Operations are applied sequentially in the order they 129 appear in the array. Each operation in the sequence is applied to 130 the target document; the resulting document becomes the target of the 131 next operation. Evaluation continues until all operations are 132 successfully applied, or an error condition is encountered. 134 4. Operations 136 Operation objects MUST have exactly one "op" member, whose value 137 indicates the operation to perform. Its value MUST be one of "add", 138 "remove", "replace", "move", "copy" or "test". The semantics of each 139 is defined below. 141 Additionally, operation objects MUST have exactly one "path" member, 142 whose value MUST be a string containing a [JSON-Pointer] value that 143 references a location within the target document to perform the 144 operation (the "target location"). 146 The meanings of other members of operation objects are defined by the 147 operation (see the subsections below). Members that are not 148 explicitly defined for the operation in question MUST be ignored. 150 Note that the ordering of members in JSON objects is not significant; 151 therefore, the following operation objects are equivalent: 153 { "op": "add", "path": "/a/b/c", "value": "foo" } 154 { "path": "/a/b/c", "op": "add", "value": "foo" } 155 { "value": "foo", "path": "/a/b/c", "op": "add" } 157 Operations are applied to the data structures represented by a JSON 158 document; i.e., after any unescaping (see [RFC4627], Section 2.5) 159 takes place. 161 4.1. add 163 The "add" operation performs the following function, depending upon 164 what the target location references: 166 o If the target location specifies an array index, a new value is 167 inserted into the array at the specified index. 169 o If the target location specifies an object member that does not 170 already exist, a new member is added to the object. 172 o If the target location specifies an object member that does exist, 173 that member's value is replaced. 175 For example: 177 { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] } 179 When the operation is applied, the target location MUST reference one 180 of: 182 o The root of the target document - whereupon the specified value 183 becomes the entire content of the target document. 185 o A member to add to an existing object - whereupon the supplied 186 value is added to that object at the indicated location. If the 187 member already exists, it is replaced by the specified value. 189 o An element to add to an existing array - whereupon the supplied 190 value is added to the array at the indicated location. Any 191 elements at or above the specified index are shifted one position 192 to the right. The specified index MUST NOT be greater than the 193 number of elements in the array. If the "-" character is used to 194 index the end of the array (see [JSON-Pointer]), this has the 195 effect of appending the value to the array. 197 Because this operation is designed to add to existing objects and 198 arrays, its target location will often not exist. Although the 199 pointer's error handling algorithm will thus be invoked, this 200 specification defines the error handling behaviour for "add" pointers 201 to ignore that error and add the value as specified. 203 However, the object itself or an array containing it does need to 204 exist, and it remains an error for that not to be the case. For 205 example, "add"ing to the path "/a/b" to this document: 207 { "a": { "foo": 1 } } 209 is not an error, because "a" exists, and "b" will be added to its 210 value. It is an error in this document: 212 { "q": { "bar": 2 } } 214 because "a" does not exist. 216 4.2. remove 218 The "remove" operation removes the value at the target location. 220 The target location MUST exist for the operation to be successful. 222 For example: 224 { "op": "remove", "path": "/a/b/c" } 226 If removing an element from an array, any elements above the 227 specified index are shifted one position to the left. 229 4.3. replace 231 The "replace" operation replaces the value at the target location 232 with a new value. The operation object MUST contain a "value" member 233 that specifies the replacement value. 235 The target location MUST exist for the operation to be successful. 237 For example: 239 { "op": "replace", "path": "/a/b/c", "value": 42 } 241 This operation is functionally identical to a "remove" operation for 242 a value, followed immediately by an "add" operation at the same 243 location with the replacement value. 245 4.4. move 247 The "move" operation removes the value at a specified location and 248 adds it to the target location. 250 The operation object MUST contain a "from" member, a string 251 containing a JSON Pointer value that references the location in the 252 target document to move the value from. 254 The "from" location MUST exist for the operation to be successful. 256 For example: 258 { "op": "move", "from": "/a/b/c", "path": "/a/b/d" } 260 This operation is functionally identical to a "remove" operation on 261 the "from" location, followed immediately by an "add" operation at 262 the target location with the value that was just removed. 264 The "from" location MUST NOT be a proper prefix of the "path" 265 location; i.e., a location cannot be moved into one of its children. 267 4.5. copy 269 The "copy" operation copies the value at a specified location to the 270 target location. 272 The operation object MUST contain a "from" member, a string 273 containing a JSON Pointer value that references the location in the 274 target document to copy the value from. 276 The "from" location MUST exist for the operation to be successful. 278 For example: 280 { "op": "copy", "from": "/a/b/c", "path": "/a/b/e" } 282 This operation is functionally identical to an "add" operation at the 283 target location using the value specified in the "from". 285 4.6. test 287 The "test" operation tests that a value at the target location is 288 equal to a specified value. 290 The operation object MUST contain a "value" member that conveys the 291 value to be compared to that at the target location. 293 The target location MUST be equal to the "value" value for the 294 operation to be considered successful. 296 Here, "equal" means that the value at the target location and that 297 conveyed by "value" are of the same JSON type, and considered equal 298 by the following rules for that type: 300 o strings: are considered equal if they contain the same number of 301 Unicode characters and their code points are position-wise equal. 303 o numbers: are considered equal if their values are numerically 304 equal. 306 o arrays: are considered equal if they contain the same number of 307 values, and each value can be considered equal to the value at the 308 corresponding position in the other array, using this list of 309 type-specific rules. 311 o objects: are considered equal if they contain the same number of 312 members, and each member can be considered equal to a member in 313 the other object, by comparing their keys as strings, and values 314 using this list of type-specific rules. 316 o literals (false, true and null): are considered equal if they are 317 the same. 319 Note that this is a logical comparison; e.g., whitespace between the 320 member values of an array is not significant. 322 Also, note that ordering of the serialisation of object members is 323 not significant. 325 For example: 327 { "op": "test", "path": "/a/b/c", "value": "foo" } 329 5. Error Handling 331 If a normative requirement is violated by a JSON Patch document, or 332 if an operation is not successful, evaluation of the JSON Patch 333 document SHOULD terminate and application of the entire patch 334 document SHALL NOT be deemed successful. 336 See [RFC5789], Section 2.2 for considerations regarding handling 337 errors when JSON Patch is used with the HTTP PATCH method, including 338 suggested status codes to use to indicate various conditions. 340 Note that the HTTP PATCH method is atomic, as per [RFC5789]. 341 Therefore, the following patch would result in no changes being made 342 to the document at all (because the "test" operation results in an 343 error). 345 [ 346 { "op": "replace", "path": "/a/b/c", "value": 42 }, 347 { "op": "test", "path": "/a/b/c", "value": "C" } 348 ] 350 6. IANA Considerations 352 The Internet media type for a JSON Patch document is application/ 353 json-patch. 355 Type name: application 357 Subtype name: json-patch 359 Required parameters: none 361 Optional parameters: none 363 Encoding considerations: binary 365 Security considerations: 366 See Security Considerations in section 7. 368 Interoperability considerations: N/A 370 Published specification: 371 [this memo] 373 Applications that use this media type: 374 Applications that manipulate JSON documents. 376 Additional information: 378 Magic number(s): N/A 380 File extension(s): .json-patch 382 Macintosh file type code(s): TEXT 384 Person & email address to contact for further information: 385 Paul C. Bryan 387 Intended usage: COMMON 389 Restrictions on usage: none 391 Author: Paul C. Bryan 393 Change controller: IETF 395 7. Security Considerations 397 This specification has the same security considerations as JSON 398 [RFC4627] and [JSON-Pointer]. 400 A few older Web browsers can be coerced into loading an arbitrary 401 JSON document whose root is an array, leading to a situation where a 402 JSON Patch document containing sensitive information could be exposed 403 to attackers, even if access is authenticated. This is known as a 404 Cross-Site Request Forgery (CSRF) attack [CSRF]. 406 However, such browsers are not widely used ( estimated to comprise 407 less than 1% of the market, at the time of writing). Publishers who 408 are nevertheless concerned about this attack are advised to avoid 409 making such documents available with HTTP GET. 411 8. Acknowledgements 413 The following individuals contributed ideas, feedback and wording to 414 this specification: 416 Mike Acar, Mike Amundsen, Cyrus Daboo, Paul Davis, Stefan Koegl, 417 Murray S. Kucherawy, Dean Landolt, Randall Leeds, James Manger, 418 Julian Reschke, James Snell, Eli Stevens and Henry S. Thompson. 420 The structure of a JSON Patch document was influenced by the XML 421 Patch document [RFC5261] specification. 423 9. References 425 9.1. Normative References 427 [JSON-Pointer] 428 Bryan, P., Zyp, K., and M. Nottingham, "JSON Pointer", 429 draft-ietf-appsawg-json-pointer-07 (work in progress), 430 November 2012. 432 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 433 Requirement Levels", BCP 14, RFC 2119, March 1997. 435 [RFC4627] Crockford, D., "The application/json Media Type for 436 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 438 9.2. Informative References 440 [CSRF] Barth, A., Jackson, C., and J. Mitchell, "Robust Defenses 441 for Cross-Site Request Forgery". 443 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 444 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 445 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 447 [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch 448 Operations Framework Utilizing XML Path Language (XPath) 449 Selectors", RFC 5261, September 2008. 451 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 452 RFC 5789, March 2010. 454 Appendix A. Examples 456 A.1. Adding an Object Member 458 An example target JSON document: 460 { "foo": "bar"} 462 A JSON Patch document: 464 [ 465 { "op": "add", "path": "/baz", "value": "qux" } 466 ] 468 The resulting JSON document: 470 { 471 "baz": "qux", 472 "foo": "bar" 473 } 475 A.2. Adding an Array Element 477 An example target JSON document: 479 { "foo": [ "bar", "baz" ] } 481 A JSON Patch document: 483 [ 484 { "op": "add", "path": "/foo/1", "value": "qux" } 485 ] 487 The resulting JSON document: 489 { "foo": [ "bar", "qux", "baz" ] } 491 A.3. Removing an Object Member 493 An example target JSON document: 495 { 496 "baz": "qux", 497 "foo": "bar" 498 } 500 A JSON Patch document: 502 [ 503 { "op": "remove", "path": "/baz" } 504 ] 506 The resulting JSON document: 508 { "foo": "bar" } 510 A.4. Removing an Array Element 512 An example target JSON document: 514 { "foo": [ "bar", "qux", "baz" ] } 516 A JSON Patch document: 518 [ 519 { "op": "remove", "path": "/foo/1" } 520 ] 522 The resulting JSON document: 524 { "foo": [ "bar", "baz" ] } 526 A.5. Replacing a Value 528 An example target JSON document: 530 { 531 "baz": "qux", 532 "foo": "bar" 533 } 535 A JSON Patch document: 537 [ 538 { "op": "replace", "path": "/baz", "value": "boo" } 539 ] 541 The resulting JSON document: 543 { 544 "baz": "boo", 545 "foo": "bar" 546 } 548 A.6. Moving a Value 550 An example target JSON document: 552 { 553 "foo": { 554 "bar": "baz", 555 "waldo": "fred" 556 }, 557 "qux": { 558 "corge": "grault" 559 } 560 } 562 A JSON Patch document: 564 [ 565 { "op": "move", "from": "/foo/waldo", "path": "/qux/thud" } 566 ] 568 The resulting JSON document: 570 { 571 "foo": { 572 "bar": "baz" 573 }, 574 "qux": { 575 "corge": "grault", 576 "thud": "fred" 577 } 578 } 580 A.7. Moving an Array Element 582 An example target JSON document: 584 { "foo": [ "all", "grass", "cows", "eat" ] } 586 A JSON Patch document: 588 [ 589 { "op": "move", "from": "/foo/1", "path": "/foo/3" } 590 ] 592 The resulting JSON document: 594 { "foo": [ "all", "cows", "eat", "grass" ] } 596 A.8. Testing a Value: Success 598 An example target JSON document: 600 { 601 "baz": "qux", 602 "foo": [ "a", 2, "c" ] 603 } 605 A JSON Patch document that will result in successful evaluation: 607 [ 608 { "op": "test", "path": "/baz", "value": "qux" }, 609 { "op": "test", "path": "/foo/1", "value": 2 } 610 ] 612 A.9. Testing a Value: Error 614 An example target JSON document: 616 { "baz": "qux" } 618 A JSON Patch document that will result in an error condition: 620 [ 621 { "op": "test", "path": "/baz", "value": "bar" } 622 ] 624 A.10. Adding a nested Member Object 626 An example target JSON document: 628 { "foo": "bar" } 630 A JSON Patch document: 632 [ 633 { "op": "add", "path": "/child", "value": { "grandchild": { } } } 634 ] 636 The resulting JSON document: 638 { 639 "foo": "bar", 640 "child": { 641 "grandchild": { 642 } 643 } 645 } 647 A.11. Ignoring Unrecognized Elements 649 An example target JSON document: 651 { "foo": "bar" } 653 A JSON Patch document: 655 [ 656 { "op": "add", "path": "/baz", "value": "qux", "xyz": 123 } 657 ] 659 The resulting JSON document: 661 { 662 "foo": "bar", 663 "baz": "qux" 664 } 666 A.12. Adding to a Non-existant Target 668 An example target JSON document: 670 { "foo": "bar" } 672 A JSON Patch document: 674 [ 675 { "op": "add", "path": "/baz/bat", "value": "qux" } 676 ] 678 This JSON Patch document, applied to the target JSON document above, 679 would result in an error (therefore not being applied) because the 680 "add" operation's target location that references neither the root of 681 the document, nor a member of an existing object, nor a member of an 682 existing array. 684 A.13. Invalid JSON Patch Document 686 A JSON Patch document: 688 [ 689 { "op": "add", "path": "/baz", "value": "qux", "op": "remove" } 690 ] 692 This JSON Patch document cannot be treated as an "add" operation 693 since there is a later "op":"remove" element. A JSON parser that 694 hides such duplicate element names therefore cannot be used unless it 695 always exposes only the last element with a given name (eg 696 "op":"remove" in this example). 698 A.14. ~ Escape Ordering 700 An example target JSON document: 702 { 703 "/": 9, 704 "~1": 10 705 } 707 A JSON Patch document: 709 [ 710 {"op": "test", "path": "/~01", "value": 10} 711 ] 713 The resulting JSON document: 715 { 716 "/": 9, 717 "~1": 10 718 } 720 A.15. Comparing Strings and Numbers 722 An example target JSON document: 724 { 725 "/": 9, 726 "~1": 10 727 } 729 A JSON Patch document: 731 [ 732 {"op": "test", "path": "/~01", "value": "10"} 733 ] 735 This results in an error, because the test fails; the document value 736 is numeric, whereas the value tested for is a string. 738 A.16. Adding an Array Value 740 An example target JSON document: 742 { "foo": ["bar"] } 744 A JSON Patch document: 746 [ 747 { "op": "add", "path": "/foo/-", "value": ["abc", "def"] } 748 ] 750 The resulting JSON document: 752 { "foo": ["bar", ["abc", "def"]] } 754 Authors' Addresses 756 Paul C. Bryan (editor) 757 Salesforce.com 759 Phone: +1 604 783 1481 760 Email: pbryan@anode.ca 762 Mark Nottingham (editor) 763 Akamai 765 Email: mnot@mnot.net