idnits 2.17.00 (12 Aug 2021) /tmp/idnits30153/draft-sayre-jump-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 17. -- Found old boilerplate from RFC 3978, Section 5.2b on line 17. -- Found old boilerplate from RFC 3978, Section 5.5 on line 600. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 611. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 618. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 624. -- The document has an RFC 3978 Section 5.2(b) Derivative Works Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. 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 RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 27, 2007) is 5592 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2426 (ref. '3') (Obsoleted by RFC 6350) ** Obsolete normative reference: RFC 2445 (ref. '4') (Obsoleted by RFC 5545) ** Obsolete normative reference: RFC 4627 (ref. '7') (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 2616 (ref. '10') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 7 errors (**), 0 flaws (~~), 1 warning (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Sayre 3 Internet-Draft Mozilla Corporation 4 Intended status: Experimental January 27, 2007 5 Expires: July 31, 2007 7 JSON Uniform Messaging Protocol (JUMP) 8 draft-sayre-jump-04.txt 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 This document may not be modified, and derivative works of it may not 17 be created. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on July 31, 2007. 37 Copyright Notice 39 Copyright (C) The Internet Society (2007). 41 Abstract 43 JUMP uses HTTP and a lightweight layout for JSON records to edit the 44 Web. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. Requirements notation . . . . . . . . . . . . . . . . . . . . 4 50 3. JUMP Records . . . . . . . . . . . . . . . . . . . . . . . . . 5 51 3.1. Standard Fields . . . . . . . . . . . . . . . . . . . . . 5 52 3.1.1. The 'type' Field . . . . . . . . . . . . . . . . . . . 5 53 3.1.2. Text Fields . . . . . . . . . . . . . . . . . . . . . 6 54 3.1.3. Other Fields . . . . . . . . . . . . . . . . . . . . . 6 55 3.2. Extension Fields . . . . . . . . . . . . . . . . . . . . . 7 56 4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 57 4.1. Annotated Arrays . . . . . . . . . . . . . . . . . . . . . 8 58 4.2. Nesting . . . . . . . . . . . . . . . . . . . . . . . . . 9 59 5. Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 60 5.1. Editing Single Records . . . . . . . . . . . . . . . . . . 11 61 5.2. Editing Individual JSON Fields . . . . . . . . . . . . . . 11 62 5.3. Editing Arrays . . . . . . . . . . . . . . . . . . . . . . 11 63 6. Common JUMP Record Types . . . . . . . . . . . . . . . . . . . 12 64 6.1. jsCalendar . . . . . . . . . . . . . . . . . . . . . . . . 12 65 6.2. jsCard . . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 6.3. jsAtom . . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 68 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 69 8.1. application/jump . . . . . . . . . . . . . . . . . . . . . 15 70 8.2. application/jumparray . . . . . . . . . . . . . . . . . . 16 71 9. Normative References . . . . . . . . . . . . . . . . . . . . . 17 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18 73 Intellectual Property and Copyright Statements . . . . . . . . . . 19 75 1. Introduction 77 JSON [7] provides an interoperable object serialization format 78 capable of representing numbers, strings, arrays, and a wide range of 79 Unicode characters. This specification defines a loosely-coupled 80 protocol based on a small set of conventions for JSON records and a 81 profile of HTTP. 83 2. Requirements notation 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in RFC 2119 [8]. 89 3. JUMP Records 91 An example JUMP record: 92 { 93 "title": "Example", 94 "text": "Text and link.", 95 "link": "http://example.com/my.html", 96 "media": "http://example.com/my.jpg", 97 "id": ["B1549145-55CB-4A6B-9526-70D370821BB5"], 98 "type": ["object"], 99 "sync": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC", 100 "tags": ["foo","bar"], 101 "self": "http://example.com/42.jump", 102 "edit": "http://example.com/edit.cgi/42" 103 } 105 Detailed field definitions can be found in Section 3.1. 107 No JUMP field is required for every record, but interoperability will 108 increase as the number of standard fields increases. Thus, a record 109 containing zero standard fields is very unlikely to interoperate with 110 any given JUMP implementation. Records without 'title' or 'text' 111 fields are also unlikely to interoperate with an independently- 112 developed JUMP implementation. Guidelines for extension fields are 113 detailed in Section 3.2. 115 3.1. Standard Fields 117 3.1.1. The 'type' Field 119 The 'type' field denotes the type its containing object. JUMP 120 records have a default type of "object". 121 "type": "object" 123 Annotated JUMP arrays (Section 4.1) MUST contain the value "array". 124 "type": "array" 126 The 'type' field can have an array as its value, in which case the 127 containing object is considered to be the union of its values. For 128 example, the following example shows a type field that contains the 129 "array" value required by JUMP arrays: 130 "type": ["array", "quux-extendo"] 132 JUMP records and fields SHOULD contain general type values whenever 133 possible, so that independent implementations can interoperate to 134 some degree. Additionaly, type names should be suitable for use as a 135 MIME parameter value. 137 3.1.2. Text Fields 139 Text fields are based on the Text Constructs found in RFC 4287, 140 section 3.1 [9]. Text fields are to be interpreted as HTML. 142 'title' A text field containing the title of the record. 144 'text' A text field containing the content or description of the 145 record. 147 3.1.3. Other Fields 149 @tbd. Not hard to predict. Borrow from email and Atom as needed. 151 'author' If 'author' has a simple value, its value is taken to be 152 the equivalent of the 'name' element specified in the Atom 153 Syndication Format [9]. If its value is an object, the 'value' 154 field corresponds to the author 'name'. 'email' and 'uri' are as 155 specified in the Atom Syndication Format [9]. If the value is an 156 array, there are multiple authors. 158 'contributor' As specified for author, with a different field name. 160 'edit' A URI [5] or IRI [6] used to edit the record. See Section 5 161 for a description of JUMP's HTTP-based editing protocol. 163 'id' One or more permanent identifiers associated with the record. 165 'lang' The natural language of the JSON record and its descendents. 166 If the value of 'lang' is an object, it may itself contain a 167 dictionary mapping keys to languages. The 'default' value covers 168 any key not explicitly mentioned. 170 'link' A URI [5] or IRI [6] used to view the record in a Web 171 browser. 173 'media' The URI [5] or IRI [6] of a media object associated with the 174 record. 176 'published' A string (or object with string value) containing a 177 timestamp formatted as an Atom Syndication Format date [9]. 179 'self' A URI [5] or IRI [6] where a read-only version of the record 180 is present. 182 'sync' A string (or object with string value) containing a token for 183 clients to use when identifing versions of a record, as with the 184 HTTP Etag header [10]. 186 'updated' A string (or object with string value) containing a 187 timestamp formatted as an Atom Syndication Format date [9]. 188 Values corresponding to the record's HTTP Last-Modified date are 189 acceptable here. 191 'tags' An array of strings or objects (with string values) 192 indicating labels that have been assigned to the record. 194 3.2. Extension Fields 195 4. Arrays 197 Sequences of JUMP records are denoted using JSON array syntax. 198 [ 199 { 200 "title": "Example", 201 "text": "Text and link.", 202 "link": "http://example.com/my.html", 203 "media": "http://example.com/my.jpg", 204 "id": ["B1549145-55CB-4A6B-9526-70D370821BB5"], 205 "type": ["object"], 206 "sync": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC", 207 "tags": ["foo","bar"], 208 "self": "http://example.com/42.jump", 209 "edit": "http://example.com/edit.cgi/42" 210 }, 211 { 212 "title": "Example 2", 213 "text": "Text and link.", 214 "link": "http://example.com/my2.html", 215 "media": "http://example.com/my2.jpg", 216 "id": ["8B6373C7-DA75-4120-A9BE-30C4CDA3CB73"], 217 "type": ["object"], 218 "sync": "BC4DEFA3-BF50-428B-8606-B3230953642A", 219 "tags": ["foo","bar"], 220 "edit": "http://example.com/edit.cgi/43" 221 } 222 ] 224 4.1. Annotated Arrays 226 JUMP arrays can be annotated by using an extra level of indirection. 228 { 229 "type": ["array", "quux-extendo"], 230 "title": "Example Annotated Array", 231 "text": "This is html by default.", 232 "quux-x": "some special extensions property", 233 "value": [ 234 { 235 "title": "Example", 236 "text": "Text and link.", 237 "link": "http://example.com/my.html", 238 "media": "http://example.com/my.jpg", 239 "id": ["B1549145-55CB-4A6B-9526-70D370821BB5"], 240 "type": ["object"], 241 "sync": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC", 242 "tags": ["foo","bar"], 243 "edit": "http://example.com/edit.cgi/42" 244 }, 245 { 246 "title": "Example 2", 247 "text": "Text and link.", 248 "link": "http://example.com/my2.html", 249 "media": "http://example.com/my2.jpg", 250 "id": ["8B6373C7-DA75-4120-A9BE-30C4CDA3CB73"], 251 "type": ["object"], 252 "sync": "BC4DEFA3-BF50-428B-8606-B3230953642A", 253 "tags": ["foo","bar"], 254 "edit": "http://example.com/edit.cgi/43" 255 } 256 ] 257 } 259 4.2. Nesting 261 JUMP records and arrays can be nested. In the following example, an 262 annotated array contains 3 elements, the second of which is an array 263 itself. 264 { 265 "type": ["array", "quux-extendo"], 266 "title": "Example Annotated Array", 267 "text": "This is html by default.", 268 "quux-x": "some special extensions property", 269 "value": [ 270 { 271 "title": "Example", 272 "text": "Text and link.", 273 "link": "http://example.com/my.html", 274 "media": "http://example.com/my.jpg", 275 "id": ["B1549145-55CB-4A6B-9526-70D370821BB5"], 277 "type": ["object"], 278 "sync": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC", 279 "tags": ["foo","bar"], 280 "edit": "http://example.com/edit.cgi/42" 281 }, 282 { 283 "title": "Example 2", 284 "text": "Text and link.", 285 "link": "http://example.com/my2.html", 286 "media": "http://example.com/my2.jpg", 287 "id": ["77FAFBB4-2BA4-4D8D-9920-CC6D610D71DA"], 288 "type": ["array"], 289 "sync": "66B38253-BF67-471F-85B8-3DA601986DB6", 290 "tags": ["foo","bar"], 291 "edit": "http://example.com/edit.cgi/43", 292 "value": [ 293 { 294 "title": "Example 2a", 295 "text": "Example 2a text.", 296 "id": "59F3938E-430E-4E72-88FC-432D4D248076", 297 "link": "http://example.com/my2.html#sectionA", 298 "media": "http://example.com/my2a.jpg" 299 }, 300 { 301 "title": "Example 2b", 302 "text": "Example 2b text.", 303 "id": "4065FDC9-05E8-42CD-A626-FC4CA27AF933", 304 "link": "http://example.com/my2.html#sectionB" 305 } 306 ] 307 }, 308 { 309 "title": "Example 3", 310 "text": "Text and link.", 311 "link": "http://example.com/my3.html", 312 "media": "http://example.com/my3.jpg", 313 "id": ["8B6373C7-DA75-4120-A9BE-30C4CDA3CB73"], 314 "type": ["object"], 315 "sync": "BC4DEFA3-BF50-428B-8606-B3230953642A", 316 "tags": ["foo","bar"], 317 "edit": "http://example.com/edit.cgi/43" 318 } 319 ] 320 } 322 5. Editing 324 JUMP records are edited using HTTP methods, like all HTTP resources. 326 5.1. Editing Single Records 328 @tbd. 330 5.2. Editing Individual JSON Fields 332 It is sometimes desirable to edit a single JSON field, rather than 333 replace the whole record. For example, given a record at the URI 334 http://example.com/foo, it should be possible to edit or add a single 335 field. 336 { 337 "title": "Example 3", 338 "text": "Text and link.", 339 "link": "http://example.com/my3.html" 340 } 342 To edit a field, the client uses the familiar slash syntax of URIs to 343 denote the object hierarchy. (note: may change this, or make it 344 configurable, but the general idea works...) 345 PUT /foo/title HTTP/1.1 346 Host: example.com 347 Content-Type: application/json 348 Content-Length: 34 350 "Example 3: This is the new title" 352 A successful request would result in the following JUMP record: 353 { 354 "title": "Example 3: This is the new title", 355 "text": "Text and link.", 356 "link": "http://example.com/my3.html" 357 } 359 The 'edit' field discussed in Section 3.1.3 provides a useful way 360 compute URIs for the client, sparing them complex path calculations. 361 (todo: example using 'edit' instead of picking out an array slice). 363 5.3. Editing Arrays 365 @tbd. 367 6. Common JUMP Record Types 369 6.1. jsCalendar 371 jsCalendar is a JSON formulation of hCalendar [1], which is based on 372 iCalendar [4]. 373 { 374 "type": ["vevent"], 375 "category": [], 376 "class": "PUBLIC", 377 "description": "A synonym for the 'text' field defined above.", 378 "dtstart-text": "A Human readable description of the start date", 379 "dtstart": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ", 380 "dtend-text": "A Human readable description of the end date", 381 "dtend": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ", 382 "duration": "", 383 "location": "In a van, down by the river.", 384 "status": "TENTATIVE", 385 "summary": "A synonym for the 'title' field defined above.", 386 "uid": "04C0CFFF-10C6-4366-A08D-114D9391D22F", 387 "url": "http://example.com", 388 "last-modified": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" 389 } 391 6.2. jsCard 393 jsCard is a JSON formulation of hCard [2], which is based on vCard 394 [3]. The TITLE property from both hCard and vCard is "vtitle" in 395 jsCard. 396 { 397 "type": ["vcard"], 398 "fn": "", 399 "n": { 400 "family-name": "", 401 "given-name": "", 402 "additional-name": "", 403 "honorific-prefix": "", 404 "honorific-suffix": "" 405 }, 406 "nickname": "", 407 "sort-string": "", 408 "url": "", 409 "email": [{ 410 "type": "", 411 "value": "" 412 }], 413 "tel": [{ 414 "type": "", 416 "value": "" 417 }], 418 "adr": { 419 "post-office-box": "", 420 "extended-address": "", 421 "street-address": "", 422 "locality": "", 423 "region": "", 424 "postal-code": "", 425 "country-name": "" 426 }, 427 "label": "", 428 "geo": { 429 "latitude": "", 430 "longitude": "" 431 }, 432 "tz": "", 433 "photo": "", 434 "logo": "", 435 "sound": "", 436 "bday": "", 437 "vtitle": "", 438 "role": "", 439 "org": { 440 "organization-name": "", 441 "organization-unit": [""], 442 }, 443 "category": [""], 444 "note": "text", 445 "class": "PUBLIC", 446 "key": "... some base64 ...", 447 "mailer": "a mailer", 448 "uid": "04C0CFFF-10C6-4366-A08D-114D9391D22F", 449 "rev-text": "A Human readable description of the revision date", 450 "rev": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" 451 } 453 6.3. jsAtom 455 [tbd] A JSON formulation of hAtom. 457 7. Security Considerations 459 None. 461 8. IANA Considerations 463 JUMP records can be identified with one of two media types, 464 'application/jump' and 'application/jumparray'. 466 8.1. application/jump 468 MIME media type name: application 470 MIME subtype name: jump 472 Mandatory parameters: None. 474 Optional parameters: 476 "types": This parameter contains some or all of the type 477 information from the internal JUMP records. 479 Encoding considerations: Identical to those of "application/json" as 480 described in RFC4627 [7], Section 6. 482 Security considerations: As defined in this specification. 484 Interoperability considerations: n/a. 486 Published specification: This specification. 488 Applications that use this media type: No known applications 489 currently use this media type. 491 Additional information: 493 Magic number(s): n/a 495 File extension: .jump 497 Macintosh File Type code: TEXT 499 Person and email address to contact for further information: Robert 500 Sayre 502 Intended usage: COMMON 504 Author/Change controller: Robert Sayre 506 8.2. application/jumparray 508 MIME media type name: application 510 MIME subtype name: jumparray 512 Mandatory parameters: None. 514 Optional parameters: 516 "types": This parameter contains some or all of the type 517 information from the internal JUMP records. 519 Encoding considerations: Identical to those of "application/json" as 520 described in RFC4627 [7], Section 6. 522 Security considerations: As defined in this specification. 524 Interoperability considerations: n/a. 526 Published specification: This specification. 528 Applications that use this media type: No known applications 529 currently use this media type. 531 Additional information: 533 Magic number(s): n/a 535 File extension: .jumpa 537 Macintosh File Type code: TEXT 539 Person and email address to contact for further information: Robert 540 Sayre 542 Intended usage: COMMON 544 Author/Change controller: Robert Sayre 546 9. Normative References 548 [1] Celik, T. and B. Suda, "hCalendar", June 2005, 549 . 551 [2] Celik, T. and B. Suda, "hCard", June 2005, 552 . 554 [3] Dawson, F. and T. Howes, "vCard MIME Directory Profile", 555 RFC 2426, September 1998. 557 [4] Dawson, F. and Stenerson, D., "Internet Calendaring and 558 Scheduling Core Object Specification (iCalendar)", RFC 2445, 559 November 1998. 561 [5] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 562 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 563 January 2005. 565 [6] Duerst, M. and M. Suignard, "Internationalized Resource 566 Identifiers (IRIs)", RFC 3987, January 2005. 568 [7] Crockford, D., "The application/json Media Type for JavaScript 569 Object Notation (JSON)", RFC 4627, July 2006. 571 [8] Bradner, S., "Key words for use in RFCs to Indicate Requirement 572 Levels", BCP 14, RFC 2119, March 1997. 574 [9] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication 575 Format", RFC 4287, December 2005. 577 [10] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 578 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 579 HTTP/1.1", RFC 2616, June 1999. 581 Author's Address 583 Robert Sayre 584 Mozilla Corporation 586 Full Copyright Statement 588 Copyright (C) The Internet Society (2007). 590 This document is subject to the rights, licenses and restrictions 591 contained in BCP 78, and except as set forth therein, the authors 592 retain all their rights. 594 This document and the information contained herein are provided on an 595 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 596 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 597 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 598 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 599 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 600 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 602 Intellectual Property 604 The IETF takes no position regarding the validity or scope of any 605 Intellectual Property Rights or other rights that might be claimed to 606 pertain to the implementation or use of the technology described in 607 this document or the extent to which any license under such rights 608 might or might not be available; nor does it represent that it has 609 made any independent effort to identify any such rights. Information 610 on the procedures with respect to rights in RFC documents can be 611 found in BCP 78 and BCP 79. 613 Copies of IPR disclosures made to the IETF Secretariat and any 614 assurances of licenses to be made available, or the result of an 615 attempt made to obtain a general license or permission for the use of 616 such proprietary rights by implementers or users of this 617 specification can be obtained from the IETF on-line IPR repository at 618 http://www.ietf.org/ipr. 620 The IETF invites any interested party to bring to its attention any 621 copyrights, patents or patent applications, or other proprietary 622 rights that may cover technology that may be required to implement 623 this standard. Please address the information to the IETF at 624 ietf-ipr@ietf.org. 626 Acknowledgment 628 Funding for the RFC Editor function is provided by the IETF 629 Administrative Support Activity (IASA).