idnits 2.17.1 draft-wilde-home-xml-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 10 instances of too long lines in the document, the longest one being 130 characters in excess of 72. ** The abstract seems to contain references ([2], [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 date (February 12, 2014) is 3718 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-06) exists of draft-nottingham-json-home-03 ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) -- Obsolete informational reference (is this intentional?): RFC 6982 (Obsoleted by RFC 7942) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft UC Berkeley 4 Intended status: Informational February 12, 2014 5 Expires: August 16, 2014 7 Home Documents for HTTP Services: XML Syntax 8 draft-wilde-home-xml-03 10 Abstract 12 The current draft for HTTP Home Documents provides a JSON syntax 13 only. This draft provides an XML syntax for the same underlying data 14 model, so that the concept of HTTP Home Documents can be consistently 15 exposed in both JSON- and XML-based HTTP services. 17 Note to Readers 19 Please discuss this draft on the apps-discuss mailing list [1]. 21 Online access to all versions and files is available on github [2]. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on August 16, 2014. 40 Copyright Notice 42 Copyright (c) 2014 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. XML Example . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 4.1. Media Type application/home+xml . . . . . . . . . . . . . 6 62 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 7 63 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 64 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 8. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 8.1. From -02 to -03 . . . . . . . . . . . . . . . . . . . . . 9 67 8.2. From -01 to -02 . . . . . . . . . . . . . . . . . . . . . 9 68 8.3. From -00 to -01 . . . . . . . . . . . . . . . . . . . . . 9 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 9.1. Normative References . . . . . . . . . . . . . . . . . . . 9 71 9.2. Informative References . . . . . . . . . . . . . . . . . . 10 72 Appendix A. XML-to-HTML for Home Documents . . . . . . . . . . . 10 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 1. Introduction 77 An Internet Draft currently under development 78 [I-D.nottingham-json-home] proposes the concept of "Home Documents 79 for HTTP APIs" and described them as follows: 81 "This document proposes a 'home document' format for non-browser HTTP 82 clients. [...] The goal of home documents is to serve as a starting 83 point for hypermedia APIs, where clients need to have an entry point, 84 and then can use the API by following links. Home documents thus 85 serve the same purpose as home pages on web sites: They are stable 86 entry points that provide starting points for clients with some 87 knowledge of the services linked from them." 89 While this general concept of a home document is independent of the 90 representation format, the current draft only defines a JSON syntax. 91 In order to make this concept available across representations, this 92 draft defines an XML syntax for the concepts defined in 93 [I-D.nottingham-json-home]. 95 At this point it is undecided whether both drafts will be merged 96 eventually, or whether they will both be published as separate 97 documents. Regardless of the final publication setup, it should be 98 noted that this draft is only defining the XML syntax, whereas all 99 the concepts represented in this syntax are defined by 100 [I-D.nottingham-json-home]. 102 One notable difference is the handling of links found in "href" or 103 "href-template" attributes on "resource" elements: In the JSON 104 syntax, these are (if they are relative URIs) resolved against the 105 URI of the home document itself. The XML syntax adds support for an 106 optional "xml:base" attribute [W3C.REC-xmlbase-20090128] on the 107 "resources" document element. If this attribute is present, it has 108 to be used according to its specification, and thus becomes part of a 109 possible resolution chain of relative URIs. 111 2. XML Example 113 The following Home Document in XML syntax uses the same data as the 114 Home Document shown in Section 2 of [I-D.nottingham-json-home] (but 115 adding xml:base="http://example.com" to demonstrate the mechanism): 117 118 119 120 121 122 125 126 127 GET 128 PUT 129 DELETE 130 PATCH 131 132 133 application/json 134 135 136 application/patch+json 137 138 139 application/xml 140 141 142 bytes 143 144 145 146 148 The mapping between JSON arrays and XML uses "item" elements , 149 where each of those elements represents one array item. For 150 properties that have a single values (i.e., they are not defined as 151 an array of values), this value is directly contained as content in 152 the corresponding element. 154 Currently, the draft does not specify an extension model (how to 155 represents hints that are not specified in the draft itself), and 156 therefore the extension model for XML is currently undefined as well. 157 The XML syntax will be updated to reflect the extension model once it 158 has been specified for the JSON syntax. 160 3. XML Schema 162 The following XML Schema is describing the XML shown in Section 2. 163 Since there currently is no extension model, the XML Schema does 164 currently not contain any extension points. 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 246 4. IANA Considerations 248 This specification registers a media type for the XML syntax of Home 249 Documents (as defined in [I-D.nottingham-json-home]). 251 4.1. Media Type application/home+xml 253 The Internet media type [RFC6838] for a Home Document in XML syntax 254 is application/home+xml. 256 Type name: application 258 Subtype name: home+xml 259 Required parameters: none 261 Optional parameters: Same as charset parameter for the media type 262 "application/xml" as specified in RFC 3023 [RFC3023]. 264 Encoding considerations: Same as encoding considerations of media 265 type "application/xml" as specified in RFC 3023 [RFC3023]. 267 Security considerations: This media type has all of the security 268 considerations described in RFC 3023 [RFC3023] and 269 [I-D.nottingham-json-home]. 271 Interoperability considerations: N/A 273 Published specification: RFC XXXX 275 Applications that use this media type: Applications that publish Home 276 Documents for HTTP services using XML syntax. 278 Additional information: 280 Magic number(s): N/A 282 File extension(s): XML documents should use ".xml" as the file 283 extension. 285 Macintosh file type code(s): TEXT 287 Person & email address to contact for further information: Erik Wilde 288 290 Intended usage: COMMON 292 Restrictions on usage: none 294 Author: Erik Wilde 296 Change controller: IETF 298 5. Implementation Status 300 Note to RFC Editor: Please remove this section before publication. 302 This section records the status of known implementations of the 303 protocol defined by this specification at the time of posting of this 304 Internet-Draft, and is based on a proposal described in RFC 6982 305 [RFC6982]. The description of implementations in this section is 306 intended to assist the IETF in its decision processes in progressing 307 drafts to RFCs. Please note that the listing of any individual 308 implementation here does not imply endorsement by the IETF. 309 Furthermore, no effort has been spent to verify the information 310 presented here that was supplied by IETF contributors. This is not 311 intended as, and must not be construed to be, a catalog of available 312 implementations or their features. Readers are advised to note that 313 other implementations may exist. 315 According to RFC 6982, "this will allow reviewers and working groups 316 to assign due consideration to documents that have the benefit of 317 running code, which may serve as evidence of valuable experimentation 318 and feedback that have made the implemented protocols more mature. 319 It is up to the individual working groups to use this information as 320 they see fit". 322 ... 324 6. Security Considerations 326 The general security considerations for XML home documents are the 327 same as those for JSON home documents, as described in the "Security 328 Considerations" of [I-D.nottingham-json-home]. The specific security 329 considerations introduced by XML as a representation format are 330 described in the "Security Considerations" of Section 4.1. 332 7. Open Issues 334 o The move from a predefined list of hints to a hint registry is not 335 yet reflected in the XML; in particular because the latest draft 336 defines the hint data model to be JSON-specific. 338 o What is the extension model for the XML syntax? Should processing 339 of other namespaces be defined as "should ignore", so that same- 340 namespace extensions are encouraged? 342 o Should the XML syntax provide support for embedded human-readable 343 documentation? This would probably not be supported in the JSON 344 syntax, but could be marked as strictly optional and XML-specific. 346 8. Change Log 348 Note to RFC Editor: Please remove this section before publication. 350 8.1. From -02 to -03 352 o Updated author address. 354 8.2. From -01 to -02 356 o Adding "Implementation Status" section according to RFC 6982 357 [RFC6982]. 359 o Adding support for @xml:base on the "resources" document element. 361 8.3. From -00 to -01 363 o Updated references from draft-nottingham-json-home-02 to 364 draft-nottingham-json-home-03 366 o Added "Security Considerations" section. 368 o Added XSLT for transforming an XML Home Document to a simple HTML 369 representation. 371 9. References 373 9.1. Normative References 375 [I-D.nottingham-json-home] 376 Nottingham, M., "Home Documents for HTTP APIs", 377 draft-nottingham-json-home-03 (work in progress), 378 May 2013. 380 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 381 Types", RFC 3023, January 2001. 383 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 384 Specifications and Registration Procedures", BCP 13, 385 RFC 6838, January 2013. 387 [W3C.REC-xml-20081126] 388 Sperberg-McQueen, C., Yergeau, F., Paoli, J., Maler, E., 389 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 390 Edition)", World Wide Web Consortium Recommendation REC- 391 xml-20081126, November 2008, 392 . 394 [W3C.REC-xmlbase-20090128] 395 Marsh, J. and R. Tobin, "XML Base (Second Edition)", World 396 Wide Web Consortium Recommendation REC-xmlbase-20090128, 397 January 2009, 398 . 400 9.2. Informative References 402 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 403 Code: The Implementation Status Section", RFC 6982, 404 July 2013. 406 [W3C.REC-xml-stylesheet-20101028] 407 Pieters, S., Clark, J., and H. Thompson, "Associating 408 Style Sheets with XML documents 1.0 (Second Edition)", 409 World Wide Web Consortium Recommendation REC-xml- 410 stylesheet-20101028, October 2010, 411 . 413 [W3C.REC-xslt-19991116] 414 Clark, J., "XSL Transformations (XSLT) Version 1.0", World 415 Wide Web Consortium Recommendation REC-xslt-19991116, 416 November 1999, 417 . 419 URIs 421 [1] 423 [2] 425 Appendix A. XML-to-HTML for Home Documents 427 The following XSLT 1.0 stylesheet [W3C.REC-xslt-19991116] transforms 428 XML Home Documents to very simple HTML renditions. By associating 429 this stylesheet [W3C.REC-xml-stylesheet-20101028] with an XML Home 430 Document, it is possible to serve XML Home Documents that will be 431 rendered in a human-friendly way when viewed in a browser. 433 434 435 436 437 438 Home Document 439 440 441

Home Document

442
    443 444
  • 445 Link Relation 446 447 : Link 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468
    469 470
    Variables:
    471
    472
      473 474 475
    • 476 477 : 478 479
      • 480       481
    482
    483     484 485
    Hints:
    486
    487
      488 489 490
    • 491 492 : 493 494 495 496 497 498 , 499 500 501 502 503 504 505 506
      • 507       508
    509
    510     511
    512
    • 513     514
515 516 517 518 519 520 521 522 523 525 Author's Address 527 Erik Wilde 528 UC Berkeley 530 Email: dret@berkeley.edu 531 URI: http://dret.net/netdret/