└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Collection+JSON - Document Format 2 | 3 | ## Description 4 | [Collection+JSON][] is a JSON-based read/write hypermedia-type designed to support management and querying of simple collections. 5 | 6 | #### Author: 7 | 8 | Mike Amundsen (mamund@yahoo.com) 9 | 10 | #### Dates: 11 | 12 | * 2011-05-04 (Created) 13 | * 2011-07-12 (Updated) 14 | 15 | #### Status: 16 | 17 | __Approved__ 18 | 19 | ## Contents 20 | 21 | 1. [General Concepts](#1-general-concepts) 22 | 2. [Objects](#2-objects) 23 | 3. [Arrays](#3-arrays) 24 | 4. [Properties](#4-properties) 25 | 5. [Link Relations](#5-link-relations) 26 | 6. [Data Types](#6-data-types) 27 | 7. [Extensibility](#7-extensibility) 28 | 8. [Acknowledgements](#8-acknowledgements) 29 | 9. [References](#9-references) 30 | 10. [Update History](#10-update-history) 31 | 32 | > __NOTE:__ 33 | > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://tools.ietf.org/html/rfc2119). 34 | 35 | ### 1. General Concepts 36 | 37 | This section contains general concepts that apply to all [Collection+JSON][] documents. 38 | 39 | The [Collection+JSON][] hypermedia type is designed to support full read/write capability for simple lists (contacts, tasks, blog entries, etc.). The standard application semantics supported by this media type include Create, Read, Update, and Delete (CRUD) along w/ support for predefined queries including query templates (similar to HTML "GET" forms). Write operations are defined using a [template][] object supplied by the server as part of the response representation. 40 | 41 | Each [item][] in a [Collection+JSON][] [collection][] has an assigned URI (via the [href][] property) and an optional array of one or more [data][] elements along with an optional array of one or more [link][] elements. Both arrays support a [name][] property for each object in the [collection][] in order to decorate these elements with domain-specific semantic information (e.g. `"data" : [{"name" : "first-name", ...},...]`). 42 | 43 | The [Collection+JSON][] hypermedia type has a limited set of predefined link relation values and supports additional values applied by implementors in order to better describe the application domain to which the media type is applied. 44 | 45 | The following sections describe the process of reading and writing data using the [Collection+JSON][] hypermedia type as well as the way to parse and execute Query Templates. Additional examples can be found in the Examples section of this documentation. 46 | 47 | #### 1.1 Reading and Writing Data 48 | 49 | The [Collection+JSON][] media type supports a limited form of read/write semantics; the Create-Read-Update-Delete (or CRUD) pattern. In addition to CRUD operations, the [Collection+JSON][] media type supports Query Templates. 50 | 51 | This section describes the details of how clients can recognize and implement reads and writes found within [Collection+JSON][] responses. 52 | 53 | ##### 1.1.1 Reading Collections 54 | 55 | To get a list of the [items][] in a collection, the client sends an HTTP GET request to the URI of a collection. A [Collection+JSON][] Document is returned which contains one or more [item][] objects in an array. The response may describe all, or only a partial list, of the [items][] in a collection. 56 | 57 | ``` 58 | *** REQUEST *** 59 | GET /my-collection/ HTTP/1.1 60 | Host: www.example.org 61 | Accept: application/vnd.collection+json 62 | 63 | *** RESPONSE *** 64 | 200 OK HTTP/1.1 65 | Content-Type: application/vnd.collection+json 66 | Content-Length: xxx 67 | 68 | { "collection" : {...}, ... } 69 | ``` 70 | 71 | ##### 1.1.2 Adding an Item 72 | 73 | To create a new [item][] in the collection, the client first uses the [template][] object to compose a valid [item][] representation and then uses HTTP POST to send that representation to the server for processing. 74 | 75 | If the [item][] resource was created successfully, the server responds with a status code of 201 and a Location header that contains the URI of the newly created [item][] resource. 76 | 77 | ``` 78 | *** REQUEST *** 79 | POST /my-collection/ HTTP/1.1 80 | Host: www.example.org 81 | Content-Type: application/vnd.collection+json 82 | 83 | { "template" : { "data" : [ ...] } } 84 | 85 | *** RESPONSE *** 86 | 201 Created HTTP/1.1 87 | Location: http://www.example.org/my-collection/1 88 | ``` 89 | 90 | ##### 1.1.3 Reading an Item 91 | 92 | Clients can retrieve an existing [item][] resource by sending an HTTP GET request to the URI of an [item][] resource. If the request is valid, the server will respond with a representation of that [item][] resource. 93 | 94 | ``` 95 | *** REQUEST *** 96 | GET /my-collection/1 HTTP/1.1 97 | Host: www.example.org 98 | Accept: application/vnd.collection+json 99 | 100 | *** RESPONSE *** 101 | 200 OK HTTP/1.1 102 | Content-Type: application/vnd.collection+json 103 | Content-Length: xxx 104 | 105 | { "collection" : { "href" : "...", "items" [ { "href" : "...", "data" : [...].} } } 106 | ``` 107 | 108 | Note that the valid response is actually a complete [collection][] document that contains only one [item][] (and possibly related [queries][] and [template][] properties). 109 | 110 | ##### 1.1.4 Updating an Item 111 | 112 | To update an existing resource, the client uses the [template][] object as a guide to composing a replacement [item][] representation and then uses HTTP PUT to send that representation to the server. 113 | 114 | If the update is successful, the server will respond with HTTP status code 200 and possibly a representation of the updated [item][] resource representation. 115 | 116 | ``` 117 | *** REQUEST *** 118 | PUT /my-collection/1 HTTP/1.1 119 | Host: www.example.org 120 | Content-Type: application/vnd.collection+json 121 | 122 | { "template" : { "data" : [ ...] } } 123 | 124 | *** RESPONSE *** 125 | 200 OK HTTP/1.1 126 | ``` 127 | 128 | ##### 1.1.5. Deleting an Item 129 | 130 | Clients can delete existing resources by sending an HTTP DELETE request to the URI of the [item][] resource. 131 | 132 | If the delete request is successful, the server SHOULD respond with an HTTP status code of 204. The server MAY respond with an updated [collection][] resource representation. 133 | 134 | ``` 135 | *** REQUEST *** 136 | DELETE /my-collection/1 HTTP/1.1 137 | Host: www.example.org 138 | 139 | *** RESPONSE *** 140 | 204 No Content HTTP/1.1 141 | ``` 142 | 143 | #### 1.2 Query Templates 144 | 145 | Clients that support the [Collection+JSON][] media type SHOULD be able to recognize and parse query templates found within responses. Query templates consist of a [data][] array associated with an [href][] property. The queries array supports query templates. 146 | 147 | For query templates, the name/value pairs of the [data][] array set are appended to the URI found in the [href][] property associated with the queries array (with a question-mark ["?"] as separator) and this new URI is sent to the processing agent. 148 | 149 | ```json 150 | // query template sample 151 | { 152 | "queries" : 153 | [ 154 | { 155 | "href" : "http://example.org/search", 156 | "rel" : "search", 157 | "prompt" : "Enter search string", 158 | "data" : 159 | [ 160 | {"name" : "search", "value" : ""} 161 | ] 162 | } 163 | ] 164 | } 165 | ``` 166 | 167 | In the above example, if the user supplied "JSON" for the value property, the user agent would construct the following URI: 168 | 169 | `http://example.org/search?search=JSON` 170 | 171 | ### 2. Objects 172 | 173 | An object is an unordered [collection][] of zero or more name/value pairs, where a [name][] is a string and a value is a string, number, boolean, null, object, or array. 174 | 175 | The following elements are always represented as objects in [Collection+JSON][] documents. They are: [collection][] error and [template][]. 176 | 177 | #### 2.1. collection 178 | 179 | The [collection][] object contains all the "records" in the representation. This is a REQUIRED object and there MUST NOT be more than one [collection][] object in a [Collection+JSON][] document. It is a top-level document property. 180 | 181 | The [collection][] object SHOULD have a version property. For this release, the value of the version property MUST be set to 1.0. If there is no version property present, it should be assumed to be set to 1.0. 182 | 183 | The [collection][] object SHOULD have an [href][] property. The [href][] property MUST contain a valid URI. This URI SHOULD represent the address used to retrieve a representation of the document. This URI MAY be used to add a new record (See Reading and Writing Data). 184 | 185 | The [collection][] object MAY have a [links][] array child property. 186 | 187 | The [collection][] object MAY have an [items][] array child property. 188 | 189 | The [collection][] object MAY have a queries array child property. 190 | 191 | The [collection][] object MAY have a [template][] object child property. 192 | 193 | The [collection][] object MAY have an error object child property. 194 | 195 | ```json 196 | // sample collection object 197 | { 198 | "collection" : 199 | { 200 | "version" : "1.0", 201 | "href" : URI, 202 | "links" : [ARRAY], 203 | "items" : [ARRAY], 204 | "queries" : [ARRAY], 205 | "template" : {OBJECT}, 206 | "error" : {OBJECT} 207 | } 208 | } 209 | ``` 210 | 211 | #### 2.2 error 212 | 213 | The error object contains additional information on the latest error condition reported by the server. This is an OPTIONAL object and there MUST NOT be more than one error object in a [Collection+JSON][] document. It is a top-level document property. 214 | 215 | The following elements MAY appear as child properties of the error object: code message and title. 216 | 217 | ```json 218 | // sample error object 219 | { 220 | "error" : 221 | { 222 | "title" : STRING, 223 | "code" : STRING, 224 | "message" : STRING 225 | } 226 | } 227 | ``` 228 | 229 | #### 2.3 template 230 | 231 | The [template][] object contains all the input elements used to add or edit [collection][] "records." This is an OPTIONAL object and there MUST NOT be more than one [template][] object in a [Collection+JSON][] document. It is a top-level document property. 232 | 233 | The [template][] object SHOULD have a [data][] array child property. 234 | 235 | ```json 236 | // sample template object 237 | { 238 | "template" : 239 | { 240 | "data" : [ARRAY] 241 | } 242 | } 243 | ``` 244 | 245 | ### 3. Arrays 246 | 247 | An array is an ordered sequence of zero or more values. 248 | 249 | The following elements are always represented as Arrays in [Collection+JSON][] documents. They are: [items][] [data][] queries and links. 250 | 251 | #### 3.1. items 252 | 253 | The [items][] array represents the list of records in the [Collection+JSON][] document. It is a child property of the [collection][] object. 254 | 255 | Each element in the [items][] array SHOULD contain an [href][] property. The [href][] property MUST contain a URI. This URI MAY be used to retrieve a [Collection+JSON][] document representing the associated item. It MAY be used to edit or delete the associated item. See Reading and Writing Data for details. 256 | 257 | The [items][] array MAY have a [data][] array child property. 258 | 259 | The [items][] array MAY have a [links][] array child property. 260 | 261 | ```json 262 | // sample items array 263 | { 264 | "collection" : 265 | { 266 | "version" : "1.0", 267 | "href" : URI, 268 | "items" : 269 | [ 270 | { 271 | "href" : URI, 272 | "data" : [ARRAY], 273 | "links" : [ARRAY] 274 | }, 275 | ... 276 | { 277 | "href" : URI, 278 | "data" : [ARRAY], 279 | "links" : [ARRAY] 280 | } 281 | ] 282 | } 283 | } 284 | ``` 285 | 286 | #### 3.2. data 287 | 288 | The [data][] array is a child property of the [items][] array and the [template][] object. 289 | 290 | The [data][] array SHOULD contain one or more anonymous objects. Each object MAY have any of three possible properties: [name][] (REQUIRED), value (OPTIONAL), and prompt (OPTIONAL). 291 | 292 | ```json 293 | // sample data array 294 | { 295 | "template" : 296 | { 297 | "data" : 298 | [ 299 | {"prompt" : STRING, "name" : STRING, "value" : VALUE}, 300 | {"prompt" : STRING, "name" : STRING, "value" : VALUE}, 301 | ... 302 | {"prompt" : STRING, "name" : STRING, "value" : VALUE} 303 | ] 304 | } 305 | } 306 | ``` 307 | 308 | #### 3.3. queries 309 | 310 | The queries array is an OPTIONAL top-level property of the [Collection+JSON][] document. 311 | 312 | The queries array SHOULD contain one or more anonymous objects. Each object composed of five possible properties: [href][] (REQUIRED), rel (REQUIRED), [name][] (OPTIONAL), prompt (OPTIONAL), and a [data][] array (OPTIONAL). 313 | 314 | If present, the [data][] array represents query parameters for the associated [href][] property of the same object. See Query Templates for details. 315 | 316 | ```json 317 | // sample queries array 318 | { 319 | "queries" : 320 | [ 321 | {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING}, 322 | {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING, 323 | "data" : 324 | [ 325 | {"name" : STRING, "value" : VALUE} 326 | ] 327 | }, 328 | ... 329 | {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING} 330 | ] 331 | } 332 | ``` 333 | 334 | #### 3.4. links 335 | 336 | The [links][] array is an OPTIONAL child property of the [items][] array. It SHOULD contain one or more anonymous objects. Each has five possible properties: [href][] (REQUIRED), rel (REQURIED), [name][] (OPTIONAL), render (OPTIONAL), and prompt, (OPTIONAL). 337 | 338 | ```json 339 | // sample links array 340 | { 341 | "collection" : 342 | { 343 | "version" : "1.0", 344 | "href" : URI, 345 | "items" : 346 | [ 347 | { 348 | "href" : URI, 349 | "data" : [ARRAY], 350 | "links" : 351 | [ 352 | {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING, "render" : "image"}, 353 | {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING, "render" : "link"}, 354 | ... 355 | {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING} 356 | ] 357 | } 358 | ] 359 | } 360 | } 361 | ``` 362 | 363 | ### 4. Properties 364 | 365 | Properties represent individual name/value pairs for objects within [Collection+JSON][] documents. 366 | 367 | #### 4.1. code 368 | 369 | The code property MAY be a child property of the error object. 370 | 371 | It SHOULD be a STRING type. 372 | 373 | #### 4.2. href 374 | 375 | The [href][] MAY be a child property of the following: [collection][] object [items][] array elements [links][] array elements and queries array elements. 376 | 377 | It MUST contain a valid URI. 378 | 379 | #### 4.3. message 380 | 381 | The message property MAY be a child property of the error object. 382 | 383 | It SHOULD be a STRING type. 384 | 385 | #### 4.4. name 386 | 387 | The [name][] property MAY be a child element of the [data][] array and the [links][] array. 388 | 389 | It SHOULD be a STRING data type. 390 | 391 | #### 4.5. prompt 392 | 393 | The prompt property MAY appear as a child property of the queries array, the [links][] array, and the [data][] array. 394 | 395 | It SHOULD be a STRING data type. 396 | 397 | #### 4.6. rel 398 | 399 | The rel MAY be a child property of the following: [links][] array elements and queries array elements. 400 | 401 | It SHOULD be a STRING data type. 402 | 403 | #### 4.7. render 404 | 405 | The render MAY be a child property of the [links][] array element. 406 | 407 | It SHOULD be a STRING data type. The value MUST be either __image__ or __link__. If the render property does not appear on a [links][] array element, it should be assumed to be set to __link__. 408 | 409 | #### 4.8. title 410 | 411 | The title property MAY be a child property of the error object. 412 | 413 | It SHOULD be a STRING type. 414 | 415 | #### 4.9. value 416 | 417 | The value property MAY be a child element of [data][] array elements 418 | 419 | It MAY contain one of the following data types: STRING NUMBER true, false or null 420 | 421 | #### 4.10. version 422 | 423 | The version SHOULD be a child property of the [collection][] collection element. It SHOULD be a STRING data type. For this release, the version SHOULD be set to 1.0. 424 | 425 | ### 5. Link Relations 426 | 427 | Link relation values can be used to annotate [links][] array and queries array properties. 428 | 429 | #### 5.1. collection 430 | 431 | The target IRI points to a resource which represents a list of which the context IRI is a member. 432 | 433 | When used in the [Collection+JSON][] media type, this link relation value refers to a [collection][] document. 434 | 435 | Logged with the [Microformats Existing Rel Values][]. 436 | 437 | #### 5.2. item 438 | 439 | The target IRI points to a resource that is a member of a [collection][] represented by the context IRI. 440 | 441 | When used in the [Collection+JSON][] media type, this link relation refers to an individual [item][] in a collection. 442 | 443 | Logged with the [Microformats Existing Rel Values][]. 444 | 445 | #### 5.3. template 446 | 447 | The target IRI points to a resource that is a representation of a valid write template for the data represented by the context IRI. 448 | 449 | When use in the [Collection+JSON][] media type, this link relation value refers to the [template][] object of a collection. 450 | 451 | #### 5.4 queries 452 | 453 | The target IRI points to a resource that is a representation of a list of valid queries that can be executed against the data represented by the context IRI. 454 | 455 | When used in the [Collection+JSON][] media type, this link relation value refers to the queries object of a collection. 456 | 457 | #### 5.5 Other Link Relation Values 458 | 459 | The [Collection+JSON][] media type has a limited set of defined link relations. Implementors are free to use any additional link relation values as needed and are encouraged to use already defined link relation values found in existing registries. 460 | 461 | Suggested registries are (but not limited to): 462 | 463 | * [IANA Link Relations](http://www.iana.org/assignments/link-relations/link-relations.xml) 464 | * [Microformats Existing Rel Values][] 465 | * [Expressing Dublin Core metadata using HTML/XHTML meta and link elements](http://dublincore.org/documents/dc-html/) 466 | 467 | Implementors may also wish to create their own unique link relation values using the standards outlined in [RFC5988](http://tools.ietf.org/html/rfc5988). 468 | 469 | ### 6. Data Types 470 | 471 | Below are the data types used in [Collection+JSON][] documents. The reference for most of the data type definitions below is the [JSON Grammar](http://tools.ietf.org/html/rfc4627#section-2) section of the [RFC4627](http://tools.ietf.org/html/rfc4627). 472 | 473 | #### 6.1. OBJECT 474 | 475 | An OBJECT structure is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members). A name is a string. A single colon comes after each name, separating the name from the value. A single comma separates a value from a following name. The names within an object SHOULD be unique. 476 | 477 | #### 6.2. ARRAY 478 | 479 | An ARRAY structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas. 480 | 481 | #### 6.3. NUMBER 482 | 483 | A NUMBER contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. 484 | 485 | Octal and hex forms are not allowed. Leading zeros are not allowed. 486 | 487 | A fraction part is a decimal point followed by one or more digits. 488 | 489 | An exponent part begins with the letter E in upper or lowercase, which may be followed by a plus or minus sign. The E and optional sign are followed by one or more digits. 490 | 491 | #### 6.4. STRING 492 | 493 | A STRING begins and ends with quotation marks. All Unicode characters may be placed within the quotation marks except for the characters that must be escaped: quotation mark, reverse solidus, and the control characters (U+0000 through U+001F). 494 | 495 | #### 6.5. URI 496 | 497 | A URI is defined by [RFC 3986](http://tools.ietf.org/html/rfc3986) 498 | 499 | #### 6.6. VALUE 500 | 501 | A VALUE data type MUST be a NUMBER, STRING, or one of the following literal names: __false__, __null__, or __true__. 502 | 503 | __NOTE__: This release of [Collection+JSON][] does not support OBJECT or ARRAY as a valid VALUE. 504 | 505 | ### 7. Extensibility 506 | 507 | This document describes the [Collection+JSON][] markup vocabulary. Markup from other vocabularies ("foreign markup") can be used in a [Collection+JSON][] document. Any extensions to the [Collection+JSON][] vocabulary MUST not redefine any objects (or their properties), arrays, properties, link relations, or data types defined in this document. Clients that do not recognize extensions to the [Collection+JSON][] vocabulary SHOULD ignore them. 508 | 509 | The details of designing and implementing [Collection+JSON][] extensions is beyond the scope of this document. 510 | 511 | __NOTE__: It is possible that future forward-compatible modifications to this specification will include new objects, arrays, properties, link-relations, and data types. Extension designers should take care to prevent future modifications from breaking or redefining those extensions. 512 | 513 | ### 8. Acknowledgements 514 | 515 | The author gratefully acknowledges the following individuals who generously contributed corrections, comments, and criticism on the design of this media type: 516 | 517 | * [Erlend Hamnaberg](http://twitter.com/hamnis) 518 | * [Nick Pendley](http://twitter.com/pc1oad1etter) 519 | * [David Metcalf](http://metcalf.net/) 520 | * (Qfwfq) 521 | 522 | ### 9. References 523 | 524 | * [RFC2119 - Key words for use in RFCs to Indicate Requirement Levels](http://tools.ietf.org/html/rfc2119) 525 | * [Create-Update-Read-Delete (CRUD) [Wikipedia]](http://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 526 | * [IANA Link Relations](http://www.iana.org/assignments/link-relations/link-relations.xml) 527 | * [Microformats Existing Rel Values](http://microformats.org/wiki/existing-rel-values) 528 | * [Paramsr.us - Registering Link Relation Types](http://paramsr.us/link-relation-types/) 529 | * [Expressing Dublin Core metadata using HTML/XHTML meta and link elements](http://dublincore.org/documents/dc-html/) 530 | * [RFC5988 - Web Linking](http://tools.ietf.org/html/rfc5988) 531 | * [RFC2627 - The application/json Media Type for JavaScript Object Notation (JSON)](http://tools.ietf.org/html/rfc4627) 532 | * [RFC3986 - Uniform Resource Identifier (URI): Generic Syntax](http://tools.ietf.org/html/rfc3986) 533 | 534 | [Collection+JSON]: http://amundsen.com/media-types/collection/format/ 535 | 536 | [query templates]: #12-query-templates 537 | 538 | [collection]: #21-collection 539 | [template]: #23-template 540 | [error]: #22-error 541 | 542 | [item]: #31-items 543 | [items]: #31-items 544 | [data]: #32-data 545 | [queries]: #33-queries 546 | [link]: #34-links 547 | [links]: #34-links 548 | 549 | [code]: #41-code 550 | [href]: #42-href 551 | [message]: #43-message 552 | [name]: #44-name 553 | [prompt]: #45-prompt 554 | [rel]: #46-rel 555 | [render]: #47-render 556 | [title]: #48-title 557 | [value]: #49-value 558 | [version]: #410-version 559 | 560 | [link relation]: #5-link-relations 561 | [additional values]: #55-other-link-relation-values 562 | [URI]: #65-uri 563 | [examples]: http://amundsen.com/media-types/collection/examples/ 564 | [CRUD]: http://en.wikipedia.org/wiki/Create,_read,_update_and_delete 565 | [Microformats Existing Rel Values]: http://microformats.org/wiki/existing-rel-values#non_HTML_rel_values 566 | --------------------------------------------------------------------------------