One document matched: draft-nottingham-link-template-00.xml

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE rfc SYSTEM "http://xml.resource.org/authoring/rfc2629.dtd" [
   <!ENTITY rfc2119 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>  
   <!ENTITY rfc2616 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'>  
   <!ENTITY rfc3986 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>  
   <!ENTITY rfc5987 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5987.xml'>  
   <!ENTITY rfc5988 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml'>  
   <!ENTITY rfc6570 SYSTEM 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml'>  
]>

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc tocdepth="3" ?>
<?rfc tocindent="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>

<rfc ipr="trust200902" docName="draft-nottingham-link-template-00" category="info">

	<front>
		<title>The Link-Template HTTP Header Field</title>
		<author initials="M." surname="Nottingham" fullname="Mark Nottingham">
			<organization>Rackspace</organization>
			<address>       
				<email>mnot@mnot.net</email> 
				<uri>http://www.mnot.net/</uri>
			</address>
		</author>
		<date year="2012"/>
		<abstract>

			<t>This specification defines the Link-Template HTTP header field,
            providing a means for describing the structure of a link between
            two resources, so that new links can be generated. </t>

		</abstract>
	</front>

	<middle>

		<section title="Introduction">

			<t><xref target="RFC6570"/> defines a syntax for templates that,
			when expanded using a set of variables, results in a URI
			<xref target="RFC3986"/>.</t>
			
			<t>This specification defines a HTTP header field for conveying
            templated links in the headers of a HTTP message. It is
            complimentary to the Link header field <xref target="RFC5988"/>,
            which carries links directly.</t>
				
		</section>

		<section title="Requirements">
		   <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
           NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
           in this document are to be interpreted as described in <xref
           target="RFC2119"/>.</t>
		</section>
		
		<section title="Notational Conventions">
			<t>This document uses the Augmented BNF defined in <xref
            target="RFC2616"/> to specify valid protocol elements.</t>
			<t>Additionally, it uses the modified "parameter" rule from <xref
            target="RFC5987"/>, and the "URI-Template" rule from <xref
            target="RFC6570"/>.</t>
		</section>

		<section anchor="header" title="The Link-Template Header Field">

			<t>The Link-Template entity-header field provides a means for
            serialising one or more links into HTTP headers. It is
            semantically equivalent to the Link header field <xref
            target="RFC5988"/>, except that it uses URI Templates <xref
            target="RFC6570"/> to convey the structure of links.</t>

			<figure>
			  <artwork xml:space="preserve"><![CDATA[
  Link-Template  = "Link-Template" ":" #linkt-value  
  linkt-value    = "<" URI-Template ">" *( ";" parameter )
]]></artwork>
			</figure>

			<t>For example:</t>

		      <figure>
		        <artwork xml:space="preserve"><![CDATA[
Link-Template: </{username}>; rel="http://example.org/rel/user"
]]></artwork>
		      </figure>

			<t>indicates that a resource with the relation type
         "http://example.org/rel/user" can be found by interpolating the
         "username" variable into the template given.</t>

			<t>The target for the link (as defined by <xref
            target="RFC5988"/>) is the result of expanding the URI Template
            <xref target="RFC6570"/> (being converted to an absolute URI after
            expansion, if necessary).</t>

			<t>The context, relation type and target attributes for the link
            are determined as defined for the Link header field in <xref
            target="RFC5988"/>.</t>

			<t>The parameters on a linkt-value have identical semantics to
            those of a Link header field <xref target="RFC5988"/>. This
            includes (but is not limited to) the use of the "rel" parameter to
            convey the relation type, the "anchor" parameter to modify the
            context IRI, and so on.</t>
				
			<t>Likewise, the requirements for parameters on linkt-values are
            the same as those for a Link header field; in particular, the
            "rel" parameter MUST NOT appear more than once, and if it does,
            the linkt-value MUST be ignored by parsers.</t>
            
         <t>This specification defines additional semantics for the
            "var-base" parameter on linkt-values; see below.</t>

		</section>

      <section title="The 'var-base' parameter">
         <t>When a linkt-value has a 'var-base' parameter, its value
            conveys a URI-reference that is used as a base URI for the
            variable names in the URI template.</t>
         
         <t>This mechanism allows template variables to be globally
         identified, rather than specific to the context of use. Dereferencing
         the URI for a particular variable might lead to more information
         about the syntax or semantics of that variable; specification of
         particular formats for this information is out of scope for this
         document.</t>
         
         <t>To determine the URI for a given variable, the value given
            is used as a base URI in reference resolution (as specified in
            <xref target="RFC3986"/>). If the resulting URI is still relative,
            the context of the link is used as the base URI in a further
            resolution; see <xref target="RFC5988"/>.</t>
            
         <t>For example:</t>

		      <figure>
		        <artwork xml:space="preserve"><![CDATA[
Link-Template: </widgets/{widget_id}>; 
               rel="http://example.org/rel/widget";
               var-base="http://example.org/vars/"
]]></artwork>
		      </figure>

         <t>indicates that a resource with the relation type
         "http;//example.org/rel/widget" can be found by interpolating the
         "http://example.org/vars/widget_id" variable into the template
         given.</t>
         
         <t>If the current context of the link is "http://example.org/", 
            the same information could be conveyed by this header field:</t>

		      <figure>
		        <artwork xml:space="preserve"><![CDATA[
Link-Template: </widgets/{widget_id}>; 
               rel="http://example.org/rel/widget";
               var-base="/vars/"
]]></artwork>
		      </figure>
         
      </section>

		<section title="Security Considerations">

			<t>The security consideration for the Link header field in <xref
            target="RFC5988"/> and those for URI Templates <xref
            target="RFC6570"/> both apply.</t>

		</section>

		<section title="IANA Considerations">

			<t>This specification enters the "Link-Template" into the
            registry of Permanent Message Header Field Names.</t>

			<t><list style="symbols">
				<t>Header Field Name: Link-Template</t>
				<t>Protocol: http</t>
				<t>Status:</t>
				<t>Reference: [this document]</t>
			</list></t>

		</section>
      
	</middle>

	<back>
		<references title="Normative References">
			&rfc2119;
			&rfc2616;
			&rfc5987;
			&rfc5988;
			&rfc6570;
		</references>

		<references title="Informative References">
			&rfc3986;
		</references>

<!--		<section title="Acknowledgements">
			<t>Thanks to 

			  for their suggestions and feedback.           
			 </t>
			<t>The author takes all responsibility for errors and
			omissions.</t>
		</section>     -->
	</back>
</rfc>