├── .gitignore ├── README.md ├── draft-00 ├── draft-00.html ├── draft-00.txt ├── draft-00.xml └── index.html ├── draft-01 ├── draft-01.html ├── draft-01.txt ├── draft-01.xml └── index.html ├── draft-02 ├── draft-02.html ├── draft-02.txt └── draft-02.xml ├── draft-03 ├── draft-03.html ├── draft-03.txt ├── draft-03.xml └── index.html ├── draft-04 ├── draft-04.html ├── draft-04.txt ├── draft-04.xml └── index.html ├── draft-05 ├── draft-05.html ├── draft-05.txt ├── draft-05.xml └── index.html ├── draft-06 ├── draft-06.html ├── draft-06.txt ├── draft-06.xml └── index.html ├── draft-07 ├── draft-07.html ├── draft-07.txt ├── draft-07.xml └── index.html ├── ex ├── contact-alps.xml ├── contact-cj.js ├── contact-hal.xml └── contact.html ├── generate_rfc ├── index.html ├── misc ├── draft-davies-template-bare.xml ├── link-rel-template.xml └── rfc-notes.txt ├── rfc2629.xslt ├── schemas ├── alps.bak ├── alps.json ├── alps.xsd ├── sample.json └── spec │ ├── alps.json │ ├── definitions.json │ └── descriptor.json └── submit /.gitignore: -------------------------------------------------------------------------------- 1 | # Compiled source # 2 | ################### 3 | *.com 4 | *.class 5 | *.dll 6 | *.exe 7 | *.o 8 | *.so 9 | 10 | # Packages # 11 | ############ 12 | # it's better to unpack these files and commit the raw source 13 | # git has its own built in compression methods 14 | *.7z 15 | *.dmg 16 | *.gz 17 | *.iso 18 | *.jar 19 | *.rar 20 | *.tar 21 | *.zip 22 | node_modules/ 23 | 24 | # Logs and databases # 25 | ###################### 26 | *.log 27 | *.sql 28 | *.sqlite 29 | 30 | # OS generated files # 31 | ###################### 32 | .DS_Store 33 | .DS_Store? 34 | ._* 35 | .Spotlight-V100 36 | .Trashes 37 | ehthumbs.db 38 | Thumbs.db 39 | *~ 40 | 41 | # local environment data # 42 | ########################## 43 | *.postman_environment.json 44 | *.env 45 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Application-Level Profile Semantics (ALPS) 2 | ==== 3 | 4 | ALPS Specification documents. 5 | 6 | ## Contributing 7 | * Fork/branch master. 8 | * Make your addition or bug fix to the the .xml version of the current draft 9 | * Generate your .txt and .html files: 10 | 11 | _Option 1_ 12 | * Using an [xml2rfc converter](/misc/rfc-notes.txt), generate the .txt and .html files. E.g., using [Python xml2rfc][]: 13 | ``` 14 | $ xml2rfc draft-00.xml --basename=draft-00 --text --html 15 | ``` 16 | 17 | NOTE: There is currently a bug in the current version (1.4.5) of the [Python xml2rfc ][] library. This bug impacts 18 | the online generator at: http://xml.resource.org/ 19 | 20 | You can work around this by using the [Python 1.4.5 xml2rfc library][] locally and making the patch discussed here: 21 | http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/239#comment:1 22 | 23 | * Copy the contents of draft-00.html to index.html. 24 | 25 | _Option 2_ 26 | * If you have [Python xml2rfc][] installed: 27 | 28 | ``` 29 | $ ./generate_rfc 30 | ``` 31 | * Open a pull request and include in the description: 32 | * The purpose of the changes. 33 | * Links to any related github issues or milestones the PR addresses. 34 | 35 | [Python xml2rfc]: https://pypi.python.org/pypi/xml2rfc 36 | -------------------------------------------------------------------------------- /draft-00/draft-00.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Network Working Group M. Amundsen 6 | Internet-Draft CA Technologies, Inc. 7 | Expires: March 6, 2015 L. Richardson 8 | 9 | M. Foster 10 | Fingi, Inc. 11 | September 2, 2014 12 | 13 | 14 | Application-Level Profile Semantics (ALPS) 15 | draft-amundsen-richardson-foster-alps-00 16 | 17 | Abstract 18 | 19 | This document describes ALPS, a data format for defining simple 20 | descriptions of application-level semantics, similar in complexity to 21 | HTML microformats. An ALPS document can be used as a profile to 22 | explain the application semantics of a document with an application- 23 | agnostic media type (such as HTML, HAL, Collection+JSON, Siren, 24 | etc.). This increases the reusability of profile documents across 25 | media types. 26 | 27 | Editorial Note (To be removed by RFC Editor) 28 | 29 | Distribution of this document is unlimited. Comments should be sent 30 | to the IETF Media-Types mailing list (see [1]). 31 | 32 | Status of This Memo 33 | 34 | This Internet-Draft is submitted in full conformance with the 35 | provisions of BCP 78 and BCP 79. 36 | 37 | Internet-Drafts are working documents of the Internet Engineering 38 | Task Force (IETF). Note that other groups may also distribute 39 | working documents as Internet-Drafts. The list of current Internet- 40 | Drafts is at http://datatracker.ietf.org/drafts/current/. 41 | 42 | Internet-Drafts are draft documents valid for a maximum of six months 43 | and may be updated, replaced, or obsoleted by other documents at any 44 | time. It is inappropriate to use Internet-Drafts as reference 45 | material or to cite them other than as "work in progress." 46 | 47 | This Internet-Draft will expire on March 6, 2015. 48 | 49 | Copyright Notice 50 | 51 | Copyright (c) 2014 IETF Trust and the persons identified as the 52 | document authors. All rights reserved. 53 | 54 | 55 | 56 | Amundsen, et al. Expires March 6, 2015 [Page 1] 57 | 58 | Internet-Draft Application-Level Profile Semantics September 2014 59 | 60 | 61 | This document is subject to BCP 78 and the IETF Trust's Legal 62 | Provisions Relating to IETF Documents 63 | (http://trustee.ietf.org/license-info) in effect on the date of 64 | publication of this document. Please review these documents 65 | carefully, as they describe your rights and restrictions with respect 66 | to this document. Code Components extracted from this document must 67 | include Simplified BSD License text as described in Section 4.e of 68 | the Trust Legal Provisions and are provided without warranty as 69 | described in the Simplified BSD License. 70 | 71 | Table of Contents 72 | 73 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 74 | 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 75 | 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 76 | 1.2.1. Describing Domain-Specific Semantics . . . . . . . . 4 77 | 1.2.2. ALPS-based Server Implementations . . . . . . . . . . 4 78 | 1.2.3. ALPS-based Client Implementations . . . . . . . . . . 4 79 | 1.3. A Simple ALPS Example . . . . . . . . . . . . . . . . . . 4 80 | 1.4. Identifying an ALPS Document . . . . . . . . . . . . . . 9 81 | 2. ALPS Documents . . . . . . . . . . . . . . . . . . . . . . . 9 82 | 2.1. Compliance . . . . . . . . . . . . . . . . . . . . . . . 10 83 | 2.2. ALPS Document Properties . . . . . . . . . . . . . . . . 10 84 | 2.2.1. 'alps' . . . . . . . . . . . . . . . . . . . . . . . 10 85 | 2.2.2. 'doc' . . . . . . . . . . . . . . . . . . . . . . . . 10 86 | 2.2.3. 'descriptor' . . . . . . . . . . . . . . . . . . . . 11 87 | 2.2.4. 'ext' . . . . . . . . . . . . . . . . . . . . . . . . 12 88 | 2.2.5. 'format' . . . . . . . . . . . . . . . . . . . . . . 13 89 | 2.2.6. 'href' . . . . . . . . . . . . . . . . . . . . . . . 14 90 | 2.2.7. 'id' . . . . . . . . . . . . . . . . . . . . . . . . 14 91 | 2.2.8. 'link' . . . . . . . . . . . . . . . . . . . . . . . 16 92 | 2.2.9. 'name' . . . . . . . . . . . . . . . . . . . . . . . 16 93 | 2.2.10. 'rel' . . . . . . . . . . . . . . . . . . . . . . . . 17 94 | 2.2.11. 'rt' . . . . . . . . . . . . . . . . . . . . . . . . 17 95 | 2.2.12. 'type' . . . . . . . . . . . . . . . . . . . . . . . 17 96 | 2.2.13. 'value' . . . . . . . . . . . . . . . . . . . . . . . 17 97 | 2.2.14. 'version' . . . . . . . . . . . . . . . . . . . . . . 18 98 | 2.3. ALPS Representations . . . . . . . . . . . . . . . . . . 18 99 | 2.3.1. Sample HTML . . . . . . . . . . . . . . . . . . . . . 18 100 | 2.3.2. XML Representation Example . . . . . . . . . . . . . 19 101 | 2.3.3. JSON Representation Example . . . . . . . . . . . . . 19 102 | 3. Applying ALPS documents to Existing Media Types . . . . . . . 21 103 | 3.1. Linking to ALPS Documents . . . . . . . . . . . . . . . . 21 104 | 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 105 | 4.1. application/alps+xml . . . . . . . . . . . . . . . . . . 22 106 | 4.2. application/alps+json . . . . . . . . . . . . . . . . . . 23 107 | 5. Internationalization Considerations . . . . . . . . . . . . . 25 108 | 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 109 | 110 | 111 | 112 | Amundsen, et al. Expires March 6, 2015 [Page 2] 113 | 114 | Internet-Draft Application-Level Profile Semantics September 2014 115 | 116 | 117 | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 118 | 7.1. Normative References . . . . . . . . . . . . . . . . . . 25 119 | 7.2. Informative References . . . . . . . . . . . . . . . . . 25 120 | Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 25 121 | A.1. Why are there no URLs in ALPS? . . . . . . . . . . . . . 25 122 | A.2. Why is there no workflow component in the ALPS 123 | specification? . . . . . . . . . . . . . . . . . . . . . 26 124 | A.3. Why is there no way to indicate ranges for semantic 125 | descriptors? . . . . . . . . . . . . . . . . . . . . . . 26 126 | 127 | 1. Introduction 128 | 129 | This document describes ALPS, a media type for defining simple 130 | descriptions of application-level semantics, similar in complexity to 131 | HTML microformats. These descriptions contain both human-readable 132 | and machine-readable explanations of the semantics. An ALPS document 133 | can be used as a profile to explain the application semantics of a 134 | document with an application-agnostic media type (such as HTML, HAL, 135 | Collection+JSON, Siren. etc.). 136 | 137 | This document identifies a registry for ALPS documents, (The ALPS 138 | Profile Registry or APR). The details of this registry, its goals, 139 | and operations are covered in a separate document (TBD). 140 | 141 | This document also identifies a process for authoring, publishing, 142 | and sharing normative human-readable instructions on applying an ALPS 143 | document as a profile to responses of a given media type. For 144 | example, a document that describes how to apply the semantics of an 145 | ALPS profile to an HTML document. 146 | 147 | This document registers two media-type identifiers with the IANA: 148 | 'application/alps+xml' ("ALPS+XML") and 'application/alps+json' 149 | ("ALPS+JSON"). 150 | 151 | 1.1. Notational Conventions 152 | 153 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 | document are to be interpreted as described in[RFC2119]. 156 | 157 | 1.2. Motivation 158 | 159 | When implementing a hypermedia client/server application using a 160 | general media type (HTML, Atom, Collection+JSON, etc.), client and 161 | server instances need to share an understanding of domain-specific 162 | information such as data element names, link relation values, and 163 | state transfer parameters. This information is directly related to 164 | the application being implemented (e.g. accounting, contact 165 | 166 | 167 | 168 | Amundsen, et al. Expires March 6, 2015 [Page 3] 169 | 170 | Internet-Draft Application-Level Profile Semantics September 2014 171 | 172 | 173 | management, etc.) rather than the media type used in the 174 | representations. 175 | 176 | 1.2.1. Describing Domain-Specific Semantics 177 | 178 | Instead of creating and registering an entirely new media type (i.e. 179 | 'application/accounting'), representation authors can create an ALPS 180 | document that describes a "profile" of the target domain; one that 181 | explains the vital domain-specific semantic descriptors and state 182 | transitions. This profile can then be consistently applied to a wide 183 | range of media types by server implementors and successfully consumed 184 | by client applications. The focus on defining application-level 185 | semantics, independent of transfer protocol or media type, makes it 186 | possible to serve application-specific representations using an 187 | application-agnostic media type. 188 | 189 | 1.2.2. ALPS-based Server Implementations 190 | 191 | Server implementors can use ALPS documents as a basis for building 192 | domain-specific solutions without having to create their own custom 193 | media type or re-invent the vocabulary and transition set for a 194 | common domain (e.g. accounting, microblogging, etc.). Using a 195 | preexisting ALPS profile as a guide, servers can map internal data to 196 | commonly-understood semantic descriptors and state transitions, 197 | increasing the likelihood that existing client applications (those 198 | who share the same understanding of the ALPS document) will be able 199 | to successfully interact with that server. 200 | 201 | 1.2.3. ALPS-based Client Implementations 202 | 203 | Armed with a document's ALPS profile, client applications can 204 | associate the ALPS descriptor 'id' and/or 'name' attribute values 205 | with the appropriate elements within the document. Client 206 | applications can "code for the profile" and better adjust to detailed 207 | changes to the response layout, or even the wholesale replacement of 208 | one media type with another. 209 | 210 | 1.3. A Simple ALPS Example 211 | 212 | Below is an ALPS document that describes elements of a simple request 213 | /response interaction in a contact management application. The 214 | profile defines a semantic descriptor called "contact", and three 215 | subordinate descriptors ("fullName", "email", and "phone"). 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | Amundsen, et al. Expires March 6, 2015 [Page 4] 225 | 226 | Internet-Draft Application-Level Profile Semantics September 2014 227 | 228 | 229 | The ALPS document also defines a single, safe state transition, to be 230 | represented by a hypermedia control (e.g. HTML.GET form) with the 231 | 'id' value of "collection." This hypermedia control has one input 232 | value ("nameSearch"). When executed, the response will contain one 233 | or more "contact" type items. 234 | 235 | 236 | A contact list. 237 | 238 | 239 | 240 | 241 | A simple link/form for getting a list of contacts. 242 | 243 | 244 | Input for a search form. 245 | 246 | 247 | 248 | 249 | 250 | 251 | A link to an individual contact. 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | ALPS Contact Profile document 260 | 261 | Implementing the ALPS profile above requires implementing the 262 | descriptors defined by the ALPS document. In this case, there are 263 | two "top level" descriptors: the safe state transition ("collection") 264 | and the semantic descriptor "contact". Below is a single HTML 265 | document that shows both these elements in a representation. 266 | 267 | 268 | 269 | 271 | 273 | 274 | 275 |
286 | 287 | 288 | 289 |
290 | 291 | 292 | 293 | 299 | 302 | 305 | 306 | 307 | 308 | 314 | 317 | 320 | 321 |
294 | 296 | Ann Arbuckle 297 | 298 | 300 | 301 | 303 | 123.456.7890 304 |
309 | 311 | Zelda Zackney 312 | 313 | 315 | 316 | 318 | 098.765.4321 319 |
322 | 323 | 324 | 325 | HTML ALPS Contact Representation 326 | 327 | HTML representations implement most ALPS elements using HTML's 328 | "class" attribute. The "collection" ID has become the CSS class of 329 | an HTML form's submit button. The "contact" ID has become the CSS 330 | class of the TR elements in an HTML table. The subordinate 331 | descriptors "fullname","email", and "phone" are rendered as the TD 332 | elements of each TR. 333 | 334 | 335 | 336 | Amundsen, et al. Expires March 6, 2015 [Page 6] 337 | 338 | Internet-Draft Application-Level Profile Semantics September 2014 339 | 340 | 341 | This HAL document uses the same profile to express the same 342 | application-level semantics as the HTML document. 343 | 344 | 345 | 347 | 350 | 351 | 353 | Ann Arbuckle 354 | aa@example.org 355 | 123.456.7890 356 | 357 | 358 | 360 | Zelda Zackney 361 | zz@example.org 362 | 987.664.3210 363 | 364 | 365 | 366 | HAL XML Contacts Representation 367 | 368 | In a HAL representation, all state transitions ("collection" and 369 | "item", in this case) are represented as link relations. All data 370 | descriptors ("fullName", "email", and "phone") are represented as XML 371 | tags named after the descriptors. 372 | 373 | This Collection+JSON document uses the ALPS profile to express the 374 | same application-level semantics as the HTML and HAL documents. 375 | 376 | { 377 | "collection" : { 378 | "version" : "1.0", 379 | "href" : "http://example.org/contacts/", 380 | 381 | "links" : [ 382 | { 383 | "rel" : "profile", 384 | "href" : "http://alps.io/profiles/contacts" 385 | }, 386 | { 387 | "rel" : "type", 388 | "href" : "http://alps.io/profiles/contacts#contact" 389 | 390 | 391 | 392 | Amundsen, et al. Expires March 6, 2015 [Page 7] 393 | 394 | Internet-Draft Application-Level Profile Semantics September 2014 395 | 396 | 397 | } 398 | ], 399 | 400 | "queries" : [ 401 | { 402 | "rel" : "collection", 403 | "rt" : "contact", 404 | "href" : "http://example.org/contacts/", 405 | "data" : [ 406 | { 407 | "name" : "nameSearch", 408 | "value" : "", 409 | "prompt" : "Search Name" 410 | } 411 | ] 412 | } 413 | ], 414 | 415 | "items" : [ 416 | { 417 | "href" : "http://example.org/contacts/1", 418 | "rel" : "item", 419 | "rt" : "contact", 420 | "data" : [ 421 | {"name" : "fullName", "value" : "Ann Arbuckle"}, 422 | {"name" : "email", "value" : "aa@example.org"}, 423 | {"name" : "phone", "value" : "123.456.7890"} 424 | ], 425 | "links" : [ 426 | { 427 | "rel" : "type", 428 | "href" : "http://alps.io/profiles/contacts#contact" 429 | } 430 | ] 431 | }, 432 | { 433 | "href" : "http://example.org/contacts/100", 434 | "rel" : "item", 435 | "rt" : "contact", 436 | "data" : [ 437 | { 438 | "name" : "fullName", 439 | "value" : "Zelda Zackney" 440 | }, 441 | { 442 | "name" : "email", 443 | "value" : "zz@example.org" 444 | }, 445 | 446 | 447 | 448 | Amundsen, et al. Expires March 6, 2015 [Page 8] 449 | 450 | Internet-Draft Application-Level Profile Semantics September 2014 451 | 452 | 453 | { 454 | "name" : "phone", 455 | "value" : "987.654.3210" 456 | } 457 | ], 458 | "links" : [ 459 | { 460 | "rel" : "type", 461 | "href" : "http://alps.io/profiles/contacts#contact" 462 | } 463 | ] 464 | } 465 | ] 466 | } 467 | } 468 | 469 | 470 | Collection+JSON Contacts Representation 471 | 472 | The descriptor "collection" has become the link relation associated 473 | with a Collection+JSON query. The descriptors "fullName", "email", 474 | and "phone" have become the names of key-value pairs in the items in 475 | a Collection+JSON collection. 476 | 477 | 1.4. Identifying an ALPS Document 478 | 479 | An ALPS vocabulary is identified by a unique URL. This URL SHOULD be 480 | assumed to be dereferencable. All ALPS URLs MUST be unique and all 481 | ALPS documents intended for public consumption SHOULD be registered 482 | in an ALPS Registry [TK: add text on where/how to find registries 483 | -mamund]. 484 | 485 | In order to reduce load on servers responding to ALPS document 486 | requests, it is RECOMMENDED that servers use cache control directives 487 | that instruct client apps to locally cache the results. Clients 488 | making these ALPS document requests SHOULD honor the server's caching 489 | directives. 490 | 491 | 2. ALPS Documents 492 | 493 | An ALPS document contains a machine-readable collection of 494 | identifying strings and their human-readable explanations. An ALPS 495 | document can be represented in either XML or JSON format. This 496 | section identifies the general elements and properties of an ALPS 497 | document, their meaning, and their use, independent of how the 498 | document is represented. Section 2.3 provides specific details on 499 | constructing a valid ALPS document in XML and in JSON format. 500 | 501 | 502 | 503 | 504 | Amundsen, et al. Expires March 6, 2015 [Page 9] 505 | 506 | Internet-Draft Application-Level Profile Semantics September 2014 507 | 508 | 509 | 2.1. Compliance 510 | 511 | An implementation is not compliant if it fails to satisfy one or more 512 | of the MUST or REQUIRED level requirements. An implementation that 513 | satisfies all the MUST or REQUIRED level and all the SHOULD level 514 | requirements is said to be "unconditionally compliant"; one that 515 | satisfies all the MUST level requirements but not all the SHOULD 516 | level requirements is said to be "conditionally compliant." 517 | 518 | 2.2. ALPS Document Properties 519 | 520 | The ALPS media type defines a small set of properties. These 521 | properties appear in both the XML and JSON formats. Below is a list 522 | of the properties that can appear in an ALPS document. 523 | 524 | 2.2.1. 'alps' 525 | 526 | Indicates the root of the ALPS document. This property is REQUIRED, 527 | and it SHOULD have one or more 'descriptor' (Section 2.2.3) child 528 | properties. 529 | 530 | Examples: 531 | 532 | XML: ... 533 | 534 | JSON: { "alps" : ... } 535 | 536 | 2.2.2. 'doc' 537 | 538 | A text field that contains free-form, usually human-readable, text. 539 | The 'doc' element MAY have two properties: 'href' (Section 2.2.6) and 540 | 'format' (Section 2.2.5). If the 'href' property appears it SHOULD 541 | contain a dereferencable URL that points to human-readable text. If 542 | the 'format' property appears it SHOULD contain one of the following 543 | values: 544 | 545 | 1. "text" 546 | 547 | 2. "html" 548 | 549 | 3. "asciidoc" 550 | 551 | Any program processing "doc" elements SHOULD honor the "format" 552 | directive and parse/render the content appropriately. If the value 553 | in the "format" property is not recognized and/or supported, the 554 | processing program MUST treat the content as plain text. If no 555 | 'format' property is present, the content SHOULD be treated as plain 556 | text. 557 | 558 | 559 | 560 | Amundsen, et al. Expires March 6, 2015 [Page 10] 561 | 562 | Internet-Draft Application-Level Profile Semantics September 2014 563 | 564 | 565 | XML:

Date of Birth

...

 566 | 567 | JSON: { "doc" : { "format" : "text" : "value" : "Date of Birth ..." 568 | } } 569 | 570 | A 'doc' element SHOULD appear as a child of 'descriptor' 571 | (Section 2.2.3). When present, it describes the meaning and use of 572 | the related 'descriptor'. 573 | 574 | XML: ... 575 | 576 | JSON: { "descriptor" : { { "doc" : { "value" : "..." } ... } } 577 | 578 | The 'doc' element MAY appear as a child of 'alps' (Section 2.2.1). 579 | When present, it describes the purpose of the ALPS document as a 580 | whole. 581 | 582 | XML: ... ... 583 | 584 | JSON: { "alps : "doc" : { "value" : "..." }, ... } 585 | 586 | 2.2.3. 'descriptor' 587 | 588 | A 'descriptor' element defines the semantics of specific data 589 | elements or state transitions that MAY exist in an associated 590 | representation. 591 | 592 | One or more 'descriptor' elements SHOULD appear as children of 'alps' 593 | (Section 2.2.1). It may also appear as a child of itself; that is, 594 | the 'descriptor' property may be nested. 595 | 596 | The 'descriptor' property SHOULD have either an 'id' (Section 2.2.7) 597 | or 'href' (Section 2.2.6) attribute. It MAY have both. 598 | Additionally, the 'descriptor' MAY have any of the following 599 | attributes: 600 | 601 | 1. 'doc' (Section 2.2.2) 602 | 603 | 2. 'ext' (Section 2.2.4) 604 | 605 | 3. 'name' (Section 2.2.9) 606 | 607 | 4. 'type' (Section 2.2.12) 608 | 609 | If present, the 'href' property MUST be a dereferenceable URL, that 610 | points to another 'descriptor' either within the current ALPS 611 | document or in another ALPS document. 612 | 613 | 614 | 615 | 616 | Amundsen, et al. Expires March 6, 2015 [Page 11] 617 | 618 | Internet-Draft Application-Level Profile Semantics September 2014 619 | 620 | 621 | If 'descriptor' has an 'href' attribute, then 'descriptor' is 622 | inheriting all the attributes and sub-properties of the descriptor 623 | pointed to by 'href'. When 'descriptor' has a property defined 624 | locally, that property value takes precedence over any inherited 625 | property value. Since there is no limit to the nesting of elements 626 | -- even ones linked remotely -- it is important to process 'all 627 | descriptor' chains starting from the bottom to make sure you have 628 | collected all the available properties and have established the 629 | correct value for each of them. 630 | 631 | If 'descriptor' is declared at the top level of an ALPS document, 632 | then a client SHOULD assume that 'descriptor' can appear anywhere in 633 | a runtime message. 634 | 635 | If 'descriptor' is nested, i.e. declared as a child of another 636 | descriptor, then: 637 | 638 | 1. A client SHOULD assume them to appear in any sibling 'descriptor' 639 | element and recursively in their child descriptors. 640 | 641 | 2. A client SHOULD NOT assume that it can appear anywhere outside of 642 | parent descriptor, unless it was explicitly referenced by another 643 | descriptor in 'href' attribute. In that case the same rules are 644 | applied to 'descriptor' containing 'href' attribute. 645 | 646 | 2.2.3.1. 'Descriptors and Link Relation Types' 647 | 648 | When a representation is generated that includes state transitions, 649 | valid values for link relation types are: 650 | 651 | 1. A registered IANA link relation type (e.g. rel="edit", a short 652 | string). 653 | 654 | 2. An extension link relation type as defined by [RFC5988] whose 655 | value is the fully-qualified URI of an associated document 656 | describing the relation type. This includes URI fragment 657 | identifiers of ALPS descriptors (e.g. rel="http://alps.io/ 658 | profiles/item#purchased-by", a URI) per the conventions of 659 | Section 2.2.7.2. 660 | 661 | 3. The 'id' property of a state transition descriptor of an 662 | associated ALPS document (e.g. rel="purchased-by", a short 663 | string) per the conventions of section Section 2.2.7.1 and 664 | Section 2.2.7.3 if the representation includes an ALPS profile. 665 | 666 | 2.2.4. 'ext' 667 | 668 | 669 | 670 | 671 | 672 | Amundsen, et al. Expires March 6, 2015 [Page 12] 673 | 674 | Internet-Draft Application-Level Profile Semantics September 2014 675 | 676 | 677 | The 'ext' element can be used to extend the ALPS document with 678 | author-specific information. It provides a way to customize ALPS 679 | documents with additional properties not covered in this 680 | specification. This is an OPTIONAL element. 681 | 682 | The 'ext' element has the following properties. 683 | 684 | 1. id (Section 2.2.7) 685 | 686 | 2. href (Section 2.2.6) 687 | 688 | 3. value (Section 2.2.13) 689 | 690 | The id (Section 2.2.7) property is REQUIRED. The href 691 | (Section 2.2.6) is RECOMMENDED and it SHOULD point to documentation 692 | that explains the use and meaning of this ext (Section 2.2.4) 693 | element. The value (Section 2.2.13) property is OPTIONAL. The 694 | content is undetermined; its meaning and use SHOULD be explained by 695 | the document found by de-referencing the href (Section 2.2.6) 696 | property. 697 | 698 | Examples: 699 | 700 | XML: 702 | 703 | JSON: { "ext" : { "id" : "directions", "href" : "http://alps.io/ext/ 704 | directions", value="north south east west" } } 705 | 706 | The 'ext' element MAY appear as a child of the following elements: 707 | 708 | 1. 'alps' (Section 2.2.1) 709 | 710 | 2. 'descriptor' (Section 2.2.3) 711 | 712 | Since the 'ext' element has no specific meaning within this 713 | specification, it MUST be ignored by any application that does not 714 | understand its meaning. 715 | 716 | 2.2.5. 'format' 717 | 718 | 719 | 720 | 721 | 722 | 723 | 724 | 725 | 726 | 727 | 728 | Amundsen, et al. Expires March 6, 2015 [Page 13] 729 | 730 | Internet-Draft Application-Level Profile Semantics September 2014 731 | 732 | 733 | Indicates how the text content should be parsed and/or rendered. 734 | This version of the spec identifies three possible values for 735 | "format": "text", "html", and "asciidoc." Any other values for this 736 | attribute are undefined and SHOULD be treated as plain text. If the 737 | program does not recognize the value of the "format" property and/or 738 | the "format" property is missing, the content SHOULD be treated as 739 | plain text. This property MAY appear as an attribute of the 'doc' 740 | (Section 2.2.2) element. 741 | 742 | 2.2.6. 'href' 743 | 744 | Contains a resolvable URL. 745 | 746 | When it appears as an attribute of 'descriptor' (Section 2.2.3), 747 | 'href' points to another 'descriptor' either within the existing ALPS 748 | document or in another ALPS document. 749 | 750 | When it appears as an attribute of 'ext' (Section 2.2.4), 'href' 751 | points to an external document which provides the defintion of the 752 | extension. 753 | 754 | When it appears as an attribute of 'link' (Section 2.2.8), 'href' 755 | points to an external document whose relationship to the current 756 | document or 'descriptor' is described by the associated 'rel' 757 | (Section 2.2.10) property. 758 | 759 | When it appears as an attribute of 'doc' (Section 2.2.2), 'href' 760 | points to a document that contains human-readable text that describes 761 | the associated 'descriptor' or ALPS document. 762 | 763 | 2.2.7. 'id' 764 | 765 | A document-wide unique identifier for the related element. This 766 | SHOULD appear as an attribute of a 'descriptor' (Section 2.2.3). 767 | 768 | The value of this attribute MAY be used as an identifier in the 769 | related runtime hypermedia representation. In the example below the 770 | ALPS descriptor with an 'id' of "q" is used to identify an HTML input 771 | element: 772 | 773 | 'id' in ALPS... 774 | 775 | ...becomes the 'class' in HTML 777 | 778 | 779 | 780 | 781 | 782 | 783 | 784 | Amundsen, et al. Expires March 6, 2015 [Page 14] 785 | 786 | Internet-Draft Application-Level Profile Semantics September 2014 787 | 788 | 789 | It should be noted that the exact mapping from ALPS elements (e.g. 790 | 'id') to elements within a particular media type (HTML, 791 | Collection+JSON, etc.) is covered in separate documents (to be 792 | specified). 793 | 794 | 2.2.7.1. ALPS 'id' and 'name' Properties 795 | 796 | In some cases, media types support non-unique identifiers (e.g. 797 | HTML's 'name' property) or will allow the same identifier value for 798 | multiple elements in the same representation (e.g.