idnits 2.17.1 draft-amundsen-richardson-foster-alps-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Since a state transition 'descriptor' may define a relation type value, it is important to avoid creating conflicts with existing IANA-registered values. If the resulting link relation type is the same as a registered relation type, the descriptor MUST not change the meaning of the IANA relation type. -- The document date (February 28, 2015) is 3338 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) -- Looks like a reference, but probably isn't: '1' on line 26 == Missing Reference: 'TK' is mentioned on line 1117, but not defined ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Downref: Normative reference to an Informational RFC: RFC 6906 ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) == Outdated reference: A later version (-12) exists of draft-ietf-appsawg-text-markdown-05 Summary: 6 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Amundsen 3 Internet-Draft CA Technologies, Inc. 4 Expires: September 1, 2015 L. Richardson 6 M. Foster 7 Apiary 8 February 28, 2015 10 Application-Level Profile Semantics (ALPS) 11 draft-amundsen-richardson-foster-alps-01 13 Abstract 15 This document describes ALPS, a data format for defining simple 16 descriptions of application-level semantics, similar in complexity to 17 HTML microformats. An ALPS document can be used as a profile to 18 explain the application semantics of a document with an application- 19 agnostic media type (such as HTML, HAL, Collection+JSON, Siren, 20 etc.). This increases the reusability of profile documents across 21 media types. 23 Editorial Note (To be removed by RFC Editor) 25 Distribution of this document is unlimited. Comments should be sent 26 to the IETF Media-Types mailing list (see [1]). 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on September 1, 2015. 45 Copyright Notice 47 Copyright (c) 2015 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 64 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4 65 1.2.1. Describing Domain-Specific Semantics . . . . . . . . 4 66 1.2.2. ALPS-based Server Implementations . . . . . . . . . . 4 67 1.2.3. ALPS-based Client Implementations . . . . . . . . . . 4 68 1.3. A Simple ALPS Example . . . . . . . . . . . . . . . . . . 5 69 1.4. Identifying an ALPS Document . . . . . . . . . . . . . . 9 70 2. ALPS Documents . . . . . . . . . . . . . . . . . . . . . . . 10 71 2.1. Compliance . . . . . . . . . . . . . . . . . . . . . . . 10 72 2.2. ALPS Document Properties . . . . . . . . . . . . . . . . 10 73 2.2.1. 'alps' . . . . . . . . . . . . . . . . . . . . . . . 10 74 2.2.2. 'doc' . . . . . . . . . . . . . . . . . . . . . . . . 10 75 2.2.3. 'descriptor' . . . . . . . . . . . . . . . . . . . . 11 76 2.2.4. 'ext' . . . . . . . . . . . . . . . . . . . . . . . . 13 77 2.2.5. 'format' . . . . . . . . . . . . . . . . . . . . . . 13 78 2.2.6. 'href' . . . . . . . . . . . . . . . . . . . . . . . 14 79 2.2.7. 'id' . . . . . . . . . . . . . . . . . . . . . . . . 14 80 2.2.8. 'link' . . . . . . . . . . . . . . . . . . . . . . . 16 81 2.2.9. 'name' . . . . . . . . . . . . . . . . . . . . . . . 16 82 2.2.10. 'rel' . . . . . . . . . . . . . . . . . . . . . . . . 17 83 2.2.11. 'rt' . . . . . . . . . . . . . . . . . . . . . . . . 17 84 2.2.12. 'type' . . . . . . . . . . . . . . . . . . . . . . . 17 85 2.2.13. 'value' . . . . . . . . . . . . . . . . . . . . . . . 18 86 2.2.14. 'version' . . . . . . . . . . . . . . . . . . . . . . 18 87 2.3. ALPS Representations . . . . . . . . . . . . . . . . . . 18 88 2.3.1. Sample HTML . . . . . . . . . . . . . . . . . . . . . 18 89 2.3.2. XML Representation Example . . . . . . . . . . . . . 19 90 2.3.3. JSON Representation Example . . . . . . . . . . . . . 19 91 3. Applying ALPS documents to Existing Media Types . . . . . . . 21 92 3.1. Linking to ALPS Documents . . . . . . . . . . . . . . . . 22 94 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 95 4.1. application/alps+xml . . . . . . . . . . . . . . . . . . 22 96 4.2. application/alps+json . . . . . . . . . . . . . . . . . . 24 97 5. Internationalization Considerations . . . . . . . . . . . . . 25 98 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 99 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 100 7.1. Normative References . . . . . . . . . . . . . . . . . . 25 101 7.2. Informative References . . . . . . . . . . . . . . . . . 25 102 Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 26 103 A.1. Why are there no URLs in ALPS? . . . . . . . . . . . . . 26 104 A.2. Why is there no workflow component in the ALPS 105 specification? . . . . . . . . . . . . . . . . . . . . . 26 106 A.3. Why is there no way to indicate ranges for semantic 107 descriptors? . . . . . . . . . . . . . . . . . . . . . . 26 109 1. Introduction 111 This document describes ALPS, a media type for defining simple 112 descriptions of application-level semantics, similar in complexity to 113 HTML microformats. These descriptions contain both human-readable 114 and machine-readable explanations of the semantics. An ALPS document 115 can be used as a profile to explain the application semantics of a 116 document with an application-agnostic media type (such as HTML, HAL, 117 Collection+JSON, Siren. etc.). 119 This document identifies a registry for ALPS documents, (The ALPS 120 Profile Registry or APR). The details of this registry, its goals, 121 and operations are covered in a separate document (TBD). 123 This document also identifies a process for authoring, publishing, 124 and sharing normative human-readable instructions on applying an ALPS 125 document as a profile to responses of a given media type. For 126 example, a document that describes how to apply the semantics of an 127 ALPS profile to an HTML document. 129 This document registers two media-type identifiers with the IANA: 130 'application/alps+xml' ('ALPS+XML') and 'application/alps+json' 131 ('ALPS+JSON'). 133 1.1. Notational Conventions 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 137 document are to be interpreted as described in[RFC2119]. 139 1.2. Motivation 141 When implementing a hypermedia client/server application using a 142 general media type (HTML, Atom, Collection+JSON, etc.), client and 143 server instances need to share an understanding of domain-specific 144 information such as data element names, link relation values, and 145 state transfer parameters. This information is directly related to 146 the application being implemented (e.g. accounting, contact 147 management, etc.) rather than the media type used in the 148 representations. 150 1.2.1. Describing Domain-Specific Semantics 152 Instead of creating and registering an entirely new media type (i.e. 153 'application/accounting'), representation authors can create an ALPS 154 document that describes a 'profile' of the target domain; one that 155 explains the vital domain-specific semantic descriptors and state 156 transitions. This profile can then be consistently applied to a wide 157 range of media types by server implementors and successfully consumed 158 by client applications. The focus on defining application-level 159 semantics, independent of transfer protocol or media type, makes it 160 possible to serve application-specific representations using an 161 application-agnostic media type. 163 1.2.2. ALPS-based Server Implementations 165 Server implementors can use ALPS documents as a basis for building 166 domain-specific solutions without having to create their own custom 167 media type or re-invent the vocabulary and transition set for a 168 common domain (e.g. accounting, microblogging, etc.). Using a 169 preexisting ALPS profile as a guide, servers can map internal data to 170 commonly-understood semantic descriptors and state transitions, 171 increasing the likelihood that existing client applications (those 172 who share the same understanding of the ALPS document) will be able 173 to successfully interact with that server. 175 1.2.3. ALPS-based Client Implementations 177 Armed with a document's ALPS profile, client applications can 178 associate the ALPS descriptor 'id' and/or 'name' attribute values 179 with the appropriate elements within the document. Client 180 applications can 'code for the profile' and better adjust to detailed 181 changes to the response layout, or even the wholesale replacement of 182 one media type with another. 184 1.3. A Simple ALPS Example 186 Below is an ALPS document that describes elements of a simple 187 request/response interaction in a contact management application. 188 The profile defines a semantic descriptor called 'contact', and three 189 subordinate descriptors ('fullName', 'email', and 'phone'). 191 The ALPS document also defines a single, safe state transition, to be 192 represented by a hypermedia control (e.g. HTML.GET form) with the 193 'id' value of 'collection.' This hypermedia control has one input 194 value ('nameSearch'). When executed, the response will contain one 195 or more 'contact' type items. 197 198 A contact list. 200 201 202 203 A simple link/form for getting a list of contacts. 204 205 206 Input for a search form. 207 208 210 211 212 213 A link to an individual contact. 214 215 216 217 218 219 221 ALPS Contact Profile document 223 Implementing the ALPS profile above requires implementing the 224 descriptors defined by the ALPS document. In this case, there are 225 two 'top level' descriptors: the safe state transition ('collection') 226 and the semantic descriptor 'contact'. Below is a single HTML 227 document that shows both these elements in a representation. 229 230 231 233 235 236 237
240 241 242 243
245 246 247 253 256 259 261 262 268 271 274 275
248 250 Ann Arbuckle 251 252 254 255 257 123.456.7890 258
263 265 Zelda Zackney 266 267 269 270 272 098.765.4321 273
276 277 279 HTML ALPS Contact Representation 281 HTML representations implement most ALPS elements using HTML's 282 'class' attribute. The 'collection' ID has become the CSS class of 283 an HTML form's submit button. The 'contact' ID has become the CSS 284 class of the TR elements in an HTML table. The subordinate 285 descriptors 'fullname','email', and 'phone' are rendered as the TD 286 elements of each TR. 288 This HAL document uses the same profile to express the same 289 application-level semantics as the HTML document. 291 292 294 297 298 300 Ann Arbuckle 301 aa@example.org 302 123.456.7890 303 304 305 307 Zelda Zackney 308 zz@example.org 309 987.664.3210 310 311 313 HAL XML Contacts Representation 315 In a HAL representation, all state transitions ('collection' and 316 'item', in this case) are represented as link relations. All data 317 descriptors ('fullName', 'email', and 'phone') are represented as XML 318 tags named after the descriptors. 320 This Collection+JSON document uses the ALPS profile to express the 321 same application-level semantics as the HTML and HAL documents. 323 { 324 "collection" : { 325 "version" : "1.0", 326 "href" : "http://example.org/contacts/", 328 "links" : [ 329 { 330 "rel" : "profile", 331 "href" : "http://alps.io/profiles/contacts" 332 }, 333 { 334 "rel" : "type", 335 "href" : "http://alps.io/profiles/contacts#contact" 336 } 337 ], 339 "queries" : [ 340 { 341 "rel" : "collection", 342 "rt" : "contact", 343 "href" : "http://example.org/contacts/", 344 "data" : [ 345 { 346 "name" : "nameSearch", 347 "value" : "", 348 "prompt" : "Search Name" 349 } 350 ] 351 } 352 ], 354 "items" : [ 355 { 356 "href" : "http://example.org/contacts/1", 357 "rel" : "item", 358 "rt" : "contact", 359 "data" : [ 360 {"name" : "fullName", "value" : "Ann Arbuckle"}, 361 {"name" : "email", "value" : "aa@example.org"}, 362 {"name" : "phone", "value" : "123.456.7890"} 363 ], 364 "links" : [ 365 { 366 "rel" : "type", 367 "href" : "http://alps.io/profiles/contacts#contact" 368 } 369 ] 370 }, 371 { 372 "href" : "http://example.org/contacts/100", 373 "rel" : "item", 374 "rt" : "contact", 375 "data" : [ 376 { 377 "name" : "fullName", 378 "value" : "Zelda Zackney" 379 }, 380 { 381 "name" : "email", 382 "value" : "zz@example.org" 383 }, 384 { 385 "name" : "phone", 386 "value" : "987.654.3210" 387 } 388 ], 389 "links" : [ 390 { 391 "rel" : "type", 392 "href" : "http://alps.io/profiles/contacts#contact" 393 } 394 ] 395 } 396 ] 397 } 398 } 400 Collection+JSON Contacts Representation 402 The descriptor 'collection' has become the link relation associated 403 with a Collection+JSON query. The descriptors 'fullName', 'email', 404 and 'phone' have become the names of key-value pairs in the items in 405 a Collection+JSON collection. 407 1.4. Identifying an ALPS Document 409 An ALPS vocabulary is identified by a unique URL. This URL SHOULD be 410 assumed to be dereferencable. All ALPS URLs MUST be unique and all 411 ALPS documents intended for public consumption SHOULD be registered 412 in an ALPS Registry [TK: add text on where/how to find registries 413 -mamund]. 415 In order to reduce load on servers responding to ALPS document 416 requests, it is RECOMMENDED that servers use cache control directives 417 that instruct client apps to locally cache the results. Clients 418 making these ALPS document requests SHOULD honor the server's caching 419 directives. 421 2. ALPS Documents 423 An ALPS document contains a machine-readable collection of 424 identifying strings and their human-readable explanations. An ALPS 425 document can be represented in either XML or JSON format. This 426 section identifies the general elements and properties of an ALPS 427 document, their meaning, and their use, independent of how the 428 document is represented. Section 2.3 provides specific details on 429 constructing a valid ALPS document in XML and in JSON format. 431 2.1. Compliance 433 An implementation is not compliant if it fails to satisfy one or more 434 of the MUST or REQUIRED level requirements. An implementation that 435 satisfies all the MUST or REQUIRED level and all the SHOULD level 436 requirements is said to be 'unconditionally compliant'; one that 437 satisfies all the MUST level requirements but not all the SHOULD 438 level requirements is said to be 'conditionally compliant.' 440 2.2. ALPS Document Properties 442 The ALPS media type defines a small set of properties. These 443 properties appear in both the XML and JSON formats. Below is a list 444 of the properties that can appear in an ALPS document. 446 2.2.1. 'alps' 448 Indicates the root of the ALPS document. This property is REQUIRED, 449 and it SHOULD have one or more 'descriptor' child properties. 451 Examples: 453 XML: ... 455 JSON: { "alps" : ... } 457 2.2.2. 'doc' 459 A text field that contains free-form, usually human-readable, text. 460 The 'doc' element MAY have two properties: 'href' and 'format'. If 461 the 'href' property appears it SHOULD contain a dereferencable URL 462 that points to human-readable text. If the 'format' property appears 463 it SHOULD contain one of the following values: 'text', 'html', 464 'asciidoc', or 'markdown'. Any program processing 'doc' elements 465 SHOULD honor the 'format' directive and parse/render the content 466 appropriately. If the value in the 'format' property is not 467 recognized and/or supported, the processing program MUST treat the 468 content as plain text. If no 'format' property is present, the 469 content SHOULD be treated as plain text. 471 XML:

Date of Birth

...

 473 JSON: { "doc" : { "format" : "text" : "value" : "Date of Birth ..." 474 } } 476 A 'doc' element SHOULD appear as a child of 'descriptor'. When 477 present, it describes the meaning and use of the related 478 'descriptor'. 480 XML: ... 482 JSON: { "descriptor" : { { "doc" : { "value" : "..." } ... } } 484 The 'doc' element MAY appear as a child of 'alps'. When present, it 485 describes the purpose of the ALPS document as a whole. 487 XML: ... ... 489 JSON: { "alps : "doc" : { "value" : "..." }, ... } 491 2.2.3. 'descriptor' 493 A 'descriptor' element defines the semantics of specific data 494 elements or state transitions that MAY exist in an associated 495 representation. 497 One or more 'descriptor' elements SHOULD appear as children of 498 'alps'. It may also appear as a child of itself; that is, the 499 'descriptor' property may be nested. 501 The 'descriptor' property SHOULD have either an 'id' or 'href' 502 attribute. It MAY have both. Additionally, the 'descriptor' MAY 503 have any of the following attributes: 505 1. 'doc' 507 2. 'ext' 509 3. 'name' 511 4. 'type' 513 If present, the 'href' property MUST be a dereferenceable URL, that 514 points to another 'descriptor' either within the current ALPS 515 document or in another ALPS document. 517 If 'descriptor' has an 'href' attribute, then 'descriptor' is 518 inheriting all the attributes and sub-properties of the descriptor 519 pointed to by 'href'. When 'descriptor' has a property defined 520 locally, that property value takes precedence over any inherited 521 property value. Since there is no limit to the nesting of elements 522 -- even ones linked remotely -- it is important to process 'all 523 descriptor' chains starting from the bottom to make sure you have 524 collected all the available properties and have established the 525 correct value for each of them. 527 If 'descriptor' is declared at the top level of an ALPS document, 528 then a client SHOULD assume that 'descriptor' can appear anywhere in 529 a runtime message. 531 If 'descriptor' is nested, i.e. declared as a child of another 532 descriptor, then: 534 1. A client SHOULD assume them to appear in any sibling 'descriptor' 535 element and recursively in their child descriptors. 537 2. A client SHOULD NOT assume that it can appear anywhere outside of 538 parent descriptor, unless it was explicitly referenced by another 539 descriptor in 'href' attribute. In that case the same rules are 540 applied to 'descriptor' containing 'href' attribute. 542 2.2.3.1. 'Descriptors and Link Relation Types' 544 When a representation is generated that includes state transitions, 545 valid values for link relation types are: 547 1. A registered IANA link relation type (e.g. rel="edit", a short 548 string). 550 2. An extension link relation type as defined by [RFC5988] whose 551 value is the fully-qualified URI of an associated document 552 describing the relation type. This includes URI fragment 553 identifiers of ALPS descriptors (e.g. 554 rel="http://alps.io/profiles/item#purchased-by", a URI) per the 555 conventions of Section 2.2.7.2. 557 3. The 'id' property of a state transition descriptor of an 558 associated ALPS document (e.g. rel="purchased-by", a short 559 string) per the conventions of section Section 2.2.7.1 and 560 Section 2.2.7.3 if the representation includes an ALPS profile. 562 2.2.4. 'ext' 564 The 'ext' element can be used to extend the ALPS document with 565 author-specific information. It provides a way to customize ALPS 566 documents with additional properties not covered in this 567 specification. This is an OPTIONAL element. 569 The 'ext' element has the following properties. 571 1. 'id' 573 2. 'href' 575 3. 'value' 577 The 'id' property is REQUIRED. The 'href' is RECOMMENDED and it 578 SHOULD point to documentation that explains the use and meaning of 579 this 'ext' element. The 'value' property is OPTIONAL. The content 580 is undetermined; its meaning and use SHOULD be explained by the 581 document found by de-referencing the 'href' property. 583 Examples: 585 XML: 588 JSON: { "ext" : { "id" : "directions", "href" : "http://alps.io/ext/ 589 directions", value="north south east west" } } 591 The 'ext' element MAY appear as a child of the following elements: 593 1. 'alps' 595 2. 'descriptor' 597 Since the 'ext' element has no specific meaning within this 598 specification, it MUST be ignored by any application that does not 599 understand its meaning. 601 2.2.5. 'format' 603 Indicates how the text content should be parsed and/or rendered. 604 This specification identifies a range of possible values for 605 'format': 607 o 'text', for plain text, MUST be supported. 609 o 'html', for HTML, SHOULD be supported. 611 o 'asciidoc', for AsciiDoc, MAY be supported. 613 o 'markdown', per The text/markdown Media Type 614 [I-D.ietf-appsawg-text-markdown], MAY be supported. 616 Any other values for this attribute are undefined and SHOULD be 617 treated as plain text. If the program does not recognize the value 618 of the 'format' property and/or the 'format' property is missing, the 619 content SHOULD be treated as plain text. 621 This property MAY appear as an attribute of the 'doc' element. 623 2.2.6. 'href' 625 Contains a resolvable URL. 627 When it appears as an attribute of a 'descriptor', 'href' points to 628 another 'descriptor' either within the existing ALPS document as a 629 fragment or in another ALPS document as an absolute URL. The URL 630 MUST contain a fragment per Section 2.2.7.2 referencing the related 631 'descriptor'. 633 When it appears as an attribute of 'ext', 'href' points to an 634 external document which provides the defintion of the extension. 636 When it appears as an attribute of 'link', 'href' points to an 637 external document whose relationship to the current document or 638 'descriptor' is described by the associated 'rel' property. 640 When it appears as an attribute of 'doc', 'href' points to a document 641 that contains human-readable text that describes the associated 642 'descriptor' or ALPS document. 644 2.2.7. 'id' 646 A document-wide unique identifier for the related element. This 647 SHOULD appear as an attribute of a 'descriptor'. 649 The value of this attribute MAY be used as an identifier in the 650 related runtime hypermedia representation. In the example below the 651 ALPS descriptor with an 'id' of 'q' is used to identify an HTML input 652 element: 654 'id' in ALPS... 656 ...becomes the 'class' in HTML 659 It should be noted that the exact mapping from ALPS elements (e.g. 660 'id') to elements within a particular media type (HTML, 661 Collection+JSON, etc.) is covered in separate documents (to be 662 specified). 664 2.2.7.1. ALPS 'id' and 'name' Properties 666 In some cases, media types support non-unique identifiers (e.g. 667 HTML's 'name' property) or will allow the same identifier value for 668 multiple elements in the same representation (e.g.