draft-gregorio-uritemplate-00.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
   <!ENTITY rfc2119 SYSTEM 'bibxml/reference.RFC.2119.xml'>
   <!ENTITY rfc3986 SYSTEM 'bibxml/reference.RFC.3986.xml'>
   <!ENTITY rfc2234 SYSTEM 'bibxml/reference.RFC.2234.xml'>
   <!ENTITY rfc2717 SYSTEM 'bibxml/reference.RFC.2717.xml'>
]>

<!-- 

$LastChangedDate: 2006-02-21 04:41:38 -0500 (Tue, 21 Feb 2006) $
$LastChangedRevision: 187 $

--> 

<!--<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>-->

<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="yes" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>
<?rfc tocdepth="3" ?>
<!-- 
1. Update the docName
2. Update the date
3. Update the Revision History.
-->
    
<!--

-->
    <rfc category="std" ipr="full3978" docName="draft-gregorio-uritemplate-00.txt">
        <front>
            <title>URI Template</title>

            <author initials='J.C.' surname="Gregorio" fullname='Joe Gregorio' role="editor">
                <organization>individual</organization>
                <address>
                    <email>joe@bitworking.org</email>
                    <uri>http://bitworking.org/</uri>
                </address>
            </author>

            <author initials='M.H.' surname="Hadley" fullname='Marc Hadley' role="editor">
                <organization>Sun Microsystems</organization>
                <address>
                    <email>Marc.Hadley@sun.com</email>
                    <uri>http://sun.com/</uri>
                </address>
            </author>

            <author initials='M.N.' surname="Nottingham" fullname='Mark Nottingham'>
                <organization>individual</organization>
                <address>
                    <email>mnot@pobox.com</email>
                    <uri>http://mnot.net/</uri>
                </address>
            </author>
 
            <author initials='D.O.' surname="Orchard" fullname='David Orchard'> 
                <organization>BEA Systems, Inc.</organization>
                <address>
                    <email>dorchard@bea.com</email>
                    <uri>http://bea.com/</uri>
                </address>
            </author>
 

            <date day="28" month="October" year="2006"/>
            <abstract>

                <t>
                    URI Templates are strings that can be transformed into URIs after embedded variables
                    are substituted. This document 
                    defines the structure and syntax of URI Templates.
                </t>

            </abstract>

            <note title="Editorial Note">
                <t>To provide feedback on this Internet-Draft, join the 
                     <eref
                        target="http://lists.w3.org/Archives/Public/uri/">W3C URI mailing
                        list (http://lists.w3.org/Archives/Public/uri/)</eref>.
                </t>
            </note>
        </front>

        <middle>

            <section title="Introduction">

                <t>
                    URI Templates are strings that contain embedded variables that 
                    are transformed into URIs after embedded variables are substituted. This document defines the 
                    structure and syntax of URI Templates.
                </t>
                <t>
                URI Templates are useful when it's necessary to convey the structure
                of a URI in a well-defined way. For example, documentation of an
                interface exposed by a Web site might use a template to show people
                how to find information about a user;
                </t>

<figure>
    <artwork>
    http://www.example.com/users/{userid}
</artwork>
</figure>

                <t>
                URI Templates can also be thought of as the basis of a machine-
                readable forms language; by allowing clients to form their own
                identifiers based on templates given to them by the URI's authority,
                it's possible to construct dynamic systems that use more of the URI
                than traditional HTML forms are able to. For example,
                </t>

<figure>
    <artwork>
    http://www.example.org/products/{upc}/buyers?page={page_num}
</artwork>
</figure>

                <t>
                Finally, URI Templates can be used to compose URI-centric protocols
                without impinging on authorities' control of their URIs. For example,
                there are many emerging conventions for passing around login
                information between sites using URIs. Forcing people to use a well-
                known query parameter isn't good practice, but using a URI parameter
                allows different sites to specify local ways of conveying the same
                information;
                </t>

<figure>
    <artwork>
    http://login.example.org/login?back={return-uri}
    http://auth.example.com/userauth;{return-uri}
</artwork>
</figure>

                <t>
                This specification defines the basic syntax and processing of URI
                Templates. Each application of URI Templates will need to define its
                own profile of this specification that indicates what template
                variables are available, how to convey them to clients, and what
                their appropriate use is in that context. 
            </t>
            </section>

            <section title="Notational Conventions">
                <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> 

                <t>
                    This specification uses the Augmented Backus-Naur Form (ABNF)
                    notation of <xref target="RFC2234"/>.
                    See <xref target="RFC3986"/> for reserved and unreserved productions. 
                </t>



            </section>

            <section title="Motivation" anchor="motivation">
                <t>
                    URI Templates are useful in a number of scenarios including web 
                    service documentation and application code. A standard syntax and well-defined
                    substitution rules will improve interop.
                </t>

            </section>


            <section title="URI Template">

                <t>
                    A URI Template is a sequence of characters that contains one or more embedded template variables 
                    <xref target="variables"/>. A URI Template becomes a URI when the template variables are substituted 
                    with the template variables string values, see <xref target="evaluating"/>.
                    The following shows an example URI Template:
                </t>

<figure>
<artwork>
http://example.com/widgets/{widget_id}
</artwork>
</figure>

<t>
    If the value of the widget_id variable is "xyzzy", the resulting URI after
    substitution is:
</t>


<figure>
<artwork>
http://example.com/widgets/xyzzy
</artwork>
</figure>

<section title="Template Variables" anchor="variables">

    <t>
        Template variables are the parameterized components of a URI Template, their representation is described below.
        A template variable MUST match the template-var production.
    </t>
    <figure>
        <artwork><![CDATA[
 template-char = unreserved 
 template-name  = 1*template-char 
 template-var  = "{" template-name "}" ]]>
</artwork>
</figure>

</section>

<section title="URI Template Substitution" anchor="evaluating">

    <t>
        Evaluating a URI Template consists of replacing each occurrence of a template variable with 
        the string value of that variable. Obtaining the string value of a template variable is an 
        application-specific process, this specification places no constraints on the mechanism employed.
        Template variables MAY appear in a URI Template any number of times.
    </t>

    <t>
        If the value of a template variable would conflict with a reserved
           character's purpose as a delimiter, then the conflicting data must be
           percent-encoded before substitution. That is, merely doing rote 
           substitution on template variables could result in the generation of an invalid URI
           for a particular scheme. Specifications that use URI Templates are
           expected to take this into consideration in how they use such templates.
    </t>
    <t>
        When the values of any template variables have been substituted into a URI template, the resulting 
        string MUST match the URI-reference production of RFC 3986 and MUST also match
        the productions for the scheme in the final URI.
    </t>
    <t>
        This specification presumes that the value of a template variable
        does not contain characters outside the
        allowed set for the component(s) of the URI that it parameterizes.
    </t>

</section>

<section title="Examples" anchor="examples">
    <t>
        Given the following template names and
        values
    </t>
<figure>
<artwork>
    Name                                Value
    ------------------------------------------------------------
    a                                   fred
    b                                   barney
    c                                   cheeseburger
    20                                  this-is-spinal-tap
    a~b                                 none%20of%20the%20above
    schema                              https
    p                                   quote=to+bo+or+not+to+be
    e                                        
    q                                   hullo#world
</artwork>
</figure>

<t>Note that the name 'wilma' has 
    not been defined, and the value of 'e' is the empty string.
</t>

<t>The following URI Templates will be expanded as shown:</t>

<figure>
<artwork>
    http://example.org/{a}/{b}/
    http://example.org/fred/barney/

    http://example.org/{a}{b}/
    http://example.org/fredbarney/

    http://example.org/page1#{a}
    http://example.org/page1#fred

    {scheme}://{20}.example.org?date={wilma}&amp;option={a}
    https://this-is-spinal-tap.example.org?date=&amp;option=fred

    http://example.org/{a~b}
    http://example.org/none%20of%20the%20above

    http://example.org?{p}
    http://example.org?quote=to+bo+or+not+to+be

    http://example.com/order/{c}/{c}/{c}/
    http://example.com/order/cheeseburger/cheeseburger/cheeseburger/

    http://example.com/{q}
    http://example.com/hullo#world

    http://example.com/{e}/
    http://example.com//
</artwork>
</figure>

<t>The following are examples of URI Template expansions that
    are not legal.
</t>

<figure>
<artwork>
    Name                                Value
    ------------------------------------------------------------
    a                                   fred barney
    b                                   % 
</artwork>
</figure>

<t>The following URI Templates are expanded with
    the given values and do not produce legal URIs.
</t>

<figure>
<artwork>
    http://example.org/{a}
    http://example.org/fred barney

    http://example.org/{b}/
    http://example.org/%/
</artwork>
</figure>


</section>

</section>

      <section title="Security Considerations">
        <t>
            A URI Template does not contain active or executable content. Other
            security considerations are the same as those for URIs, see section 7
            of RFC3986.
        </t>
      </section>

      <section title="IANA Considerations" anchor="iana">
          <t>In common with RFC3986, URI scheme names form a registered namespace
              that is managed by IANA according to the procedures defined in
              <xref target="RFC2717"/>.  No IANA actions are required by this document.
          </t>
      </section>


  </middle>
  <back> 


      <references title='Normative References'>
          &rfc2119; &rfc3986; &rfc2234; &rfc2717; 
      </references>


      <section title="Contributors">
          <t>
              The following people made significant contributions to this specification: DeWitt Clinton and James Snell.
          </t>
      </section>


      <section title="Revision History">
          <t>00 - Initial Revision.
          </t>
          </section>

      </back>
  </rfc>