idnits 2.17.1
draft-hammer-hostmeta-15.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 :
----------------------------------------------------------------------------
** 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 use 'NOT RECOMMENDED' as an RFC 2119 keyword, but
does not include the phrase in its RFC 2119 key words list.
-- The document date (May 9, 2011) is 4736 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)
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110)
** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159)
** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615)
** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288)
-- Possible downref: Non-RFC (?) normative reference: ref. '1'
Summary: 6 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. Hammer-Lahav
3 Internet-Draft Yahoo!
4 Intended status: Standards Track B. Cook
5 Expires: November 10, 2011 May 9, 2011
7 Web Host Metadata
8 draft-hammer-hostmeta-15
10 Abstract
12 This specification describes a method for locating host metadata as
13 well as information about individual resources controlled by the
14 host.
16 Editorial Note (to be removed by RFC Editor)
18 Please discuss this draft on the apps-discuss@ietf.org [1] mailing
19 list.
21 Status of this Memo
23 This Internet-Draft is submitted in full conformance with the
24 provisions of BCP 78 and BCP 79.
26 Internet-Drafts are working documents of the Internet Engineering
27 Task Force (IETF). Note that other groups may also distribute
28 working documents as Internet-Drafts. The list of current Internet-
29 Drafts is at http://datatracker.ietf.org/drafts/current/.
31 Internet-Drafts are draft documents valid for a maximum of six months
32 and may be updated, replaced, or obsoleted by other documents at any
33 time. It is inappropriate to use Internet-Drafts as reference
34 material or to cite them other than as "work in progress."
36 This Internet-Draft will expire on November 10, 2011.
38 Copyright Notice
40 Copyright (c) 2011 IETF Trust and the persons identified as the
41 document authors. All rights reserved.
43 This document is subject to BCP 78 and the IETF Trust's Legal
44 Provisions Relating to IETF Documents
45 (http://trustee.ietf.org/license-info) in effect on the date of
46 publication of this document. Please review these documents
47 carefully, as they describe your rights and restrictions with respect
48 to this document. Code Components extracted from this document must
49 include Simplified BSD License text as described in Section 4.e of
50 the Trust Legal Provisions and are provided without warranty as
51 described in the Simplified BSD License.
53 Table of Contents
55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
56 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3
57 1.1.1. Processing Resource-Specific Information . . . . . . . 5
58 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 6
59 2. Obtaining host-meta Documents . . . . . . . . . . . . . . . . 6
60 3. The host-meta Document . . . . . . . . . . . . . . . . . . . . 7
61 3.1. XML Document format . . . . . . . . . . . . . . . . . . . 8
62 3.1.1. The 'Link' Element . . . . . . . . . . . . . . . . . . 8
63 4. Processing host-meta Documents . . . . . . . . . . . . . . . . 10
64 4.1. Host-Wide Information . . . . . . . . . . . . . . . . . . 10
65 4.2. Resource-Specific Information . . . . . . . . . . . . . . 10
66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
68 6.1. The 'host-meta' Well-Known URI . . . . . . . . . . . . . . 12
69 6.2. The 'lrdd' Relation Type . . . . . . . . . . . . . . . . . 12
70 Appendix A. JRD Document Format . . . . . . . . . . . . . . . . . 13
71 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 16
72 7. Normative References . . . . . . . . . . . . . . . . . . . . . 16
73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16
75 1. Introduction
77 Web-based protocols often require the discovery of host policy or
78 metadata, where "host" is not a single resource but the entity
79 controlling the collection of resources identified by Uniform
80 Resource Identifiers (URI) with a common URI host [RFC3986].
82 While web protocols have a wide range of metadata needs, they often
83 use metadata that is concise, has simple syntax requirements, and can
84 benefit from storing their metadata in a common location used by
85 other related protocols.
87 Because there is no URI or representation available to describe a
88 host, many of the methods used for associating per-resource metadata
89 (such as HTTP headers) are not available. This often leads to the
90 overloading of the root HTTP resource (e.g. 'http://example.com/')
91 with host metadata that is not specific or relevant to the root
92 resource itself.
94 This specification registers the well-known URI suffix "host-meta" in
95 the Well-Known URI Registry established by [RFC5785], and specifies a
96 simple, general-purpose metadata document format for hosts, to be
97 used by multiple web-based protocols.
99 In addition, there are times when a host-wide scope for policy or
100 metadata is too coarse-grained. host-meta provides two mechanisms for
101 providing resource-specific information:
103 o Link Templates - links using a URI template instead of a fixed
104 target URI, providing a way to define generic rules for generating
105 resource-specific links by applying the individual resource URI to
106 the template.
108 o Link-based Resource Descriptor Documents (LRDD, pronounced 'lard')
109 - descriptor documents providing resource-specific information,
110 typically information that cannot be expressed using link
111 templates. LRDD documents are linked to resources or host-meta
112 documents using link templates with the "lrdd" relation type.
114 1.1. Example
116 The following is a simple host-meta document including both host-wide
117 and resource-specific information for the 'example.com' host:
119
120
122
124 1.0
126
129
131
134
138
141
143 The host-wide information which applies to host in its entirety
144 provided by the document includes:
146 o A "http://protocol.example.net/version" host property with a value
147 of "1.0".
149 o A link to the host's copyright policy ("copyright").
151 The resource-specific information provided by the document includes:
153 o A link template for receiving real-time updates ("hub") about
154 individual resources. Since the template does not include a
155 template variable, the target URI is identical for all resources.
157 o A LRDD document link template ("lrdd") for obtaining additional
158 resource-specific information contained in a separate document for
159 each individual resource.
161 o A link template for finding information about the author of
162 individual resources ("author").
164 1.1.1. Processing Resource-Specific Information
166 When looking for information about the an individual resource, for
167 example, the resource identified by 'http://example.com/xy', the
168 resource URI is applied to the templates found, producing the
169 following links:
171
174
178
181 The LRDD document for 'http://example.com/xy' is obtained using an
182 HTTP "GET" request:
184
185
187 http://example.com/xy
189 red
191
194
196
198 Together, the information available about the individual resource
199 (presented as an XRD document for illustration purposes) is:
201
202
204 http://example.com/xy
206 red
208
211
214
217
220
222 Note that the order of links matters and is based on their original
223 order in the host-meta and LRDD documents. For example, the "hub"
224 link obtained from the host-meta link template has a higher priority
225 than the link found in the LRDD document because the host-meta link
226 appears before the "lrdd" link.
228 On the other hand, the "author" link found in the LRDD document has a
229 higher priority than the link found in the host-meta document because
230 it appears after the "lrdd" link.
232 1.2. Notational Conventions
234 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
235 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
236 document are to be interpreted as described in [RFC2119].
238 This document uses the Augmented Backus-Naur Form (ABNF) notation of
239 [RFC5234]. Additionally, the following rules are included from
240 [RFC3986]: reserved, unreserved, and pct-encoded.
242 2. Obtaining host-meta Documents
244 The client obtains the host-meta document for a given host by sending
245 an HTTP [RFC2616] or an HTTPS [RFC2818] GET request to the host for
246 the "/.well-known/host-meta" path, using the default ports defined
247 for each protocol (e.g. port 80 for HTTP and port 443 for HTTPS).
248 The scope and meaning of host-meta documents obtained via other
249 protocols or ports is undefined.
251 The server MUST support at least one protocol but MAY support both.
252 If both protocols are supported, they MUST produce the same document.
254 The decision which protocol is used to obtain the host-meta document
255 have significant security ramifications as described in Section 5.
257 For example, the following request is used to obtain the host-meta
258 document for the 'example.com' host:
260 GET /.well-known/host-meta HTTP/1.1
261 Host: example.com
263 If the server response indicates that the host-meta resource is
264 located elsewhere (a 301, 302, or 307 response status code), the
265 client MUST try to obtain the resource from the location provided in
266 the response. This means that the host-meta document for one host
267 MAY be retrieved from another host. Likewise, if the resource is not
268 available or does not exist (e.g. a 404 or 410 response status codes)
269 using both the HTTP and HTTPS protocols, the client should infer that
270 metadata is not available via this mechanism.
272 The host-meta document SHOULD be served with the
273 "application/xrd+xml" media type. [[ media type registration pending
274 ]]
276 3. The host-meta Document
278 The host-meta document uses the XRD 1.0 document format as defined by
279 [OASIS.XRD-1.0], which provides a simple and extensible XML-based
280 schema for describing resources. This specification defines
281 additional processing rules needed to describe hosts. Documents MAY
282 include any XRD element not explicitly excluded.
284 The server MAY offer alternative representations of any XRD document
285 it serves (host-meta, LRDD, or other XRD-based documents). The
286 client MAY request a particular representation using the HTTP
287 "Accept" request header field. If no "Accept" request header field
288 is included with the request, or if the client requests a
289 "application/xrd+xml" representation, the server MUST respond using
290 the REQUIRED XRD 1.0 XML representation described in Section 3.1.
292 The XRD 1.0 XML representation is the only canonical representation
293 for any XRD document. If there is any discrepancy between the
294 content of the XRD 1.0 XML representation and any other
295 representation for the same resource, the client MUST only use the
296 XRD 1.0 XML representation.
298 Applications using the host-meta document MAY require the server to
299 provide a specific alternative representation in addition to the XRD
300 1.0 XML representation when explicitly requested by the client.
302 A JavaScript Object Notation (JSON) XRD 1.0 representation is
303 described in Appendix A.
305 3.1. XML Document format
307 The host-meta document root MUST be an "XRD" element. The document
308 SHOULD NOT include a "Subject" element, as at this time no URI is
309 available to identify hosts. The use of the "Alias" element in host-
310 meta is undefined and NOT RECOMMENDED.
312 The subject (or "context resource" as defined by [RFC5988]) of the
313 XRD "Property" and "Link" elements is the host described by the host-
314 meta document. However, the subject of "Link" elements with a
315 "template" attribute is the individual resource whose URI is applied
316 to the link template as described in Section 3.1.1.
318 3.1.1. The 'Link' Element
320 The XRD "Link" element, when used with the "href" attribute, conveys
321 a link relation between the host described by the document and a
322 common target URI.
324 For example, the following link declares a common copyright license
325 for the entire scope:
327
329 However, a "Link" element with a "template" attribute conveys a
330 relation whose context is an individual resource within the host-meta
331 document scope, and whose target is constructed by applying the
332 context resource URI to the template. The template string MAY
333 contain a URI string without any variables to represent a resource-
334 level relation that is identical for every individual resource.
336 For example, a blog with multiple authors can provide information
337 about each article's author by providing an endpoint with a parameter
338 set to the URI of each article. Each article has a unique author,
339 but all share the same pattern of where that information is located:
341
344 3.1.1.1. Template Syntax
346 This specification defines a simple template syntax for URI
347 transformation. A template is a string containing brace-enclosed
348 ("{}") variable names marking the parts of the string that are to be
349 substituted by the corresponding variable values.
351 Before substituting template variables, values MUST be encoded using
352 UTF-8 and any character other than unreserved (as defined by
353 [RFC3986]) MUST be percent-encoded per [RFC3986].
355 This specification defines a single variable - "uri" - as the entire
356 context resource URI. Protocols MAY define additional relation-
357 specific variables and syntax rules, but SHOULD only do so for
358 protocol-specific relation types, and MUST NOT change the meaning of
359 the "uri" variable. If a client is unable to successfully process a
360 template (e.g. unknown variable names, unknown or incompatible
361 syntax) the parent "Link" element SHOULD be ignored.
363 The template syntax ABNF:
365 URI-Template = *( uri-char / variable )
366 variable = "{" var-name "}"
367 uri-char = ( reserved / unreserved / pct-encoded )
368 var-name = %x75.72.69 / ( 1*var-char ) ; "uri" or other names
369 var-char = ALPHA / DIGIT / "." / "_"
371 For example:
373 Input: http://example.com/r?f=1
374 Template: http://example.org/?q={uri}
375 Output: http://example.org/?q=http%3A%2F%2Fexample.com%2Fr%3Ff%3D1
377 4. Processing host-meta Documents
379 Once the host-meta document has been obtained, the client processes
380 its content based on the type of information desired: host-wide or
381 resource-specific.
383 Clients usually look for a link with a specific relation type or
384 other attributes. In such cases, the client does not need to process
385 the entire host-meta document and all linked LRDD documents, but
386 instead, process the various documents in their prescribed order
387 until the desired information is found.
389 Protocols using host-meta must indicate whether the information they
390 seek is host-wide or resource-specific. For example, "obtain the
391 first host-meta resource-specific link using the 'author' relation
392 type". If both types are used for the same purpose (e.g. first look
393 for resource-specific, then look for host-wide), the protocol must
394 specify the processing order.
396 4.1. Host-Wide Information
398 When looking for host-wide information, the client MUST ignore any
399 "Link" elements with a "template" attribute, as well as any link
400 using the "lrdd" relation type. All other elements are scoped as
401 host-wide.
403 4.2. Resource-Specific Information
405 Unlike host-wide information which is contained solely within the
406 host-meta document, resource-specific information is obtained from
407 host-meta link templates, as well as from linked LRDD documents.
409 When looking for resource-specific information, the client constructs
410 a resource descriptor by collecting and processing all the host-meta
411 link templates. For each link template:
413 1. The client applies the URI of the desired resource to the
414 template, producing a resource-specific link.
416 2. If the link's relation type is other than "lrdd", the client adds
417 the link to the resource descriptor in order.
419 3. If the link's relation type is "lrdd":
421 3.1 The client obtains the LRDD document by following the
422 scheme-specific rules for the LRDD document URI. If the
423 document URI scheme is "http" or "https", the document is
424 obtained via an HTTP "GET" request to the identified URI.
426 If the HTTP response status code is 301, 302, or 307, the
427 client MUST follow the redirection response and repeat the
428 request with the provided location.
430 3.2 The client adds any links found in the LRDD document to the
431 resource descriptor in order, except for any link using the
432 "lrdd" relation type (processing is limited to a single
433 level of inclusion). When adding links, the client SHOULD
434 retain any extension attributes and child elements if
435 present (e.g. or elements).
437 3.3 The client adds any resource properties found in the LRDD
438 document to the resource descriptor in order (e.g.
439 or child elements of the LRDD document root
440 element).
442 5. Security Considerations
444 The host-meta document is designed to be used by other applications
445 explicitly "opting-in" to use the facility. Therefore, any such
446 application MUST review the specific security implications of using
447 host-meta documents. By itself, this specification does not provide
448 any protections or guarantees that any given host-meta document is
449 under the control of the appropriate entity as required by each
450 application.
452 The metadata returned by the host-meta resource is presumed to be
453 under the control of the appropriate authority and representative of
454 all the resources described by it. If this resource is compromised
455 or otherwise under the control of another party, it may represent a
456 risk to the security of the server and data served by it, depending
457 on the applications using it.
459 Applications utilizing the host-meta document for sensitive or
460 security related information MUST require the use of the HTTPS
461 protocol and MUST NOT produce a host-meta document using other means.
462 In addition, such applications MUST require that any redirection
463 leading to the retrieval of a host-meta document also utilize the
464 HTTPS protocol.
466 Since the host-meta document is authoritative for the entire host,
467 not just the authority (combination of scheme, host, and port) of the
468 host-meta document server, applications MUST ensure that using a
469 host-meta document for another URI authority does not represent a
470 potential security exploit.
472 Protocols using host-meta templates must evaluate the construction of
473 their templates as well as any protocol-specific variables or syntax
474 to ensure that the templates cannot be abused by an attacker. For
475 example, a client can be tricked into following a malicious link due
476 to a poorly constructed template which produces unexpected results
477 when its variable values contain unexpected characters.
479 6. IANA Considerations
481 6.1. The 'host-meta' Well-Known URI
483 This specification registers the "host-meta" well-known URI in the
484 Well-Known URI Registry as defined by [RFC5785].
486 URI suffix: host-meta
488 Change controller: IETF
490 Specification document(s): [[ this document ]]
492 Related information: The "host-meta" documents obtained from the
493 same host using the HTTP and HTTPS protocols (using default ports)
494 MUST be identical.
496 6.2. The 'lrdd' Relation Type
498 This specification registers the "lrdd" relation type in the Link
499 Relation Type Registry defined by [RFC5988]:
501 Relation Name: lrdd
503 Description: "lrdd" (pronounced 'lard') is an acronym for Link-based
504 Resource Descriptor Document. It is used by the host-meta
505 document processor to locate resource-specific information about
506 individual resources. When used elsewhere (e.g. in HTTP "Link"
507 header fields or in HTML elements), it operates as an
508 include directive, identifying the location of additional links
509 and other metadata. Multiple links with the 'lrdd' relation
510 indicate multiple sources to include, not alternative sources of
511 the same information. An "application/xrd+xml" representation
512 MUST be available, and this media type MAY appear in a link's
513 "type" attribute. Additional representations MAY be available
514 (using the HTTP "Accept" request header field), in which case the
515 link's "type" attribute SHOULD be omitted.
517 Reference: [[ This specification ]]
519 Appendix A. JRD Document Format
521 The JRD document format - a general purpose XRD 1.0 represenation -
522 uses the JavaScript Object Notation (JSON) format defined in
523 [RFC4627]. JRD uses the same elements and processing rules described
524 in Section 3.1. The JRD format is designed to include the same base
525 functionality provided by the XML format with the exception of
526 extensibility which is beyond the scope of this specification.
528 The client MAY requst a JRD representation using the HTTP "Accept"
529 request header field with value of "application/json". The server
530 MUST include the HTTP "Content-Type" response header field with value
531 of "application/json". Any other "Content-Type" value (or lack of)
532 indicates that the server does not support the JRD format.
534 XRD elements are serialized into a JSON structure as follows:
536 o The XML document declaration and "XRD" element are discarded.
538 o The "Subject" element is included as name/value pair with the name
539 'subject', and value included as a string.
541 o The "Expires" element is included as name/value pair with the name
542 'expires', and value included as a string.
544 o "Alias" elements are included as a single name/value pair with the
545 name 'alias', and value a string array containing the values of
546 each element in order.
548 o "Property" elements are included as a single object with the name
549 'properties', and value an object with each element included as a
550 name/value pair with the value of the "type" attribute as name,
551 and element value included as a string value. The values of
552 properties with empty values (i.e. using the REQUIRED
553 "xsi:nil='true'" attribute) are included as "null". If more than
554 one "Property" element is present with the same "type" attribute,
555 only the last instance is included.
557 o "Link" elements are included as a single name/value pair with the
558 name 'links' and with each element included as an object. Each
559 attribute is included as name/value pair with the attribute name
560 as name, and value included as a string.
562 o "Link" child "Property" elements are included using the same
563 method as XRD-level "Property" elements using a name/value pair
564 inside the link object.
566 o "Link" child "Title" elements are included as a single object with
567 the name 'titles', and value an object with each element included
568 as a name/value pair with the value of the "xml:lang" attribute as
569 name, and element value included as a string value. The names of
570 elements without a "xml:lang" attribute are added with the name
571 'default'. If more than one "Title" element is present with the
572 same (or no) "xml:lang" attribute, only the last instance is
573 included.
575 o The conversion of any other element is left undefined.
577 For example, the following XRD document:
579
580
583 http://blog.example.com/article/id/314
584 2010-01-30T09:30:00Z
586 http://blog.example.com/cool_new_thing
587 http://blog.example.com/steve/article/7
589 1.2
590 1.3
591
593
595 About the Author
596 Author Information
597 editor
598
600
601 The other guy
602 The other author
603
605
607
609 Is represented by the following JRD document:
611 {
612 "subject":"http://blog.example.com/article/id/314",
613 "expires":"2010-01-30T09:30:00Z",
615 "aliases":[
616 "http://blog.example.com/cool_new_thing",
617 "http://blog.example.com/steve/article/7"],
619 "properties":{
620 "http://blgx.example.net/ns/version":"1.3",
621 "http://blgx.example.net/ns/ext":null
622 },
624 "links":[
625 {
626 "rel":"author",
627 "type":"text/html",
628 "href":"http://blog.example.com/author/steve",
629 "titles":{
630 "default":"About the Author",
631 "en-us":"Author Information"
632 },
633 "properties":{
634 "http://example.com/role":"editor"
635 }
636 },
637 {
638 "rel":"author",
639 "href":"http://example.com/author/john",
640 "titles":{
641 "default":"The other author"
642 }
643 },
644 {
645 "rel":"copyright",
646 "template":"http://example.com/copyright?id={uri}"
647 }
648 ]
649 }
651 Appendix B. Acknowledgments
653 The authors would like to acknowledge the contributions of everyone
654 who provided feedback and use cases for this specification; in
655 particular, Dirk Balfanz, DeWitt Clinton, Eve Maler, Breno de
656 Medeiros, Brad Fitzpatrick, James Manger, Will Norris, Mark
657 Nottingham, John Panzer, Drummond Reed, and Peter Saint-Andre.
659 7. Normative References
661 [OASIS.XRD-1.0]
662 Hammer-Lahav, E. and W. Norris, "Extensible Resource
663 Descriptor (XRD) Version 1.0",
664 .
666 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
667 Requirement Levels", BCP 14, RFC 2119, March 1997.
669 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
670 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
671 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
673 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
675 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
676 Resource Identifier (URI): Generic Syntax", STD 66,
677 RFC 3986, January 2005.
679 [RFC4627] Crockford, D., "The application/json Media Type for
680 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
682 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
683 Specifications: ABNF", STD 68, RFC 5234, January 2008.
685 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
686 Uniform Resource Identifiers (URIs)", RFC 5785,
687 April 2010.
689 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
691 [1]
693 Authors' Addresses
695 Eran Hammer-Lahav
696 Yahoo!
698 Email: eran@hueniverse.com
699 URI: http://hueniverse.com
701 Blaine Cook
703 Email: romeda@gmail.com
704 URI: http://romeda.org