draft-gregorio-uritemplate-00.txt		draft-gregorio-uritemplate-01.txt
	Network Working Group J. Gregorio, Ed.		Network Working Group J. Gregorio, Ed.
	Internet-Draft individual		Internet-Draft
	Expires: May 1, 2007 M. Hadley, Ed.		Intended status: Standards Track M. Hadley, Ed.
	Sun Microsystems		Expires: January 10, 2008 Sun Microsystems
	M. Nottingham		M. Nottingham, Ed.
	individual
	D. Orchard		D. Orchard
	BEA Systems, Inc.		BEA Systems, Inc.
	October 28, 2006		July 9, 2007
	URI Template		URI Template
	draft-gregorio-uritemplate-00.txt		draft-gregorio-uritemplate-01
	Status of this Memo		Status of this Memo
	By submitting this Internet-Draft, each author represents that any		By submitting this Internet-Draft, each author represents that any
	applicable patent or other IPR claims of which he or she is aware		applicable patent or other IPR claims of which he or she is aware
	have been or will be disclosed, and any of which he or she becomes		have been or will be disclosed, and any of which he or she becomes
	aware will be disclosed, in accordance with Section 6 of BCP 79.		aware will be disclosed, in accordance with Section 6 of BCP 79.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF), its areas, and its working groups. Note that		Task Force (IETF), its areas, and its working groups. Note that
	skipping to change at page 1, line 39		skipping to change at page 1, line 39
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	The list of current Internet-Drafts can be accessed at		The list of current Internet-Drafts can be accessed at
	http://www.ietf.org/ietf/1id-abstracts.txt.		http://www.ietf.org/ietf/1id-abstracts.txt.
	The list of Internet-Draft Shadow Directories can be accessed at		The list of Internet-Draft Shadow Directories can be accessed at
	http://www.ietf.org/shadow.html.		http://www.ietf.org/shadow.html.
	This Internet-Draft will expire on May 1, 2007.		This Internet-Draft will expire on January 10, 2008.
	Copyright Notice		Copyright Notice
	Copyright (C) The Internet Society (2006).		Copyright (C) The IETF Trust (2007).
	Abstract		Abstract
	URI Templates are strings that can be transformed into URIs after		URI Templates are strings that can be transformed into URIs after
	embedded variables are substituted. This document defines the		embedded variables are substituted. This document defines the syntax
	structure and syntax of URI Templates.		and processing of URI Templates.
	Editorial Note		Editorial Note
	To provide feedback on this Internet-Draft, join the W3C URI mailing		To provide feedback on this Internet-Draft, join the W3C URI mailing
	list (http://lists.w3.org/Archives/Public/uri/) [1].		list (http://lists.w3.org/Archives/Public/uri/) [1].
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3		2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3
	3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 4		3. URI Template . . . . . . . . . . . . . . . . . . . . . . . . . 4
	4. URI Template . . . . . . . . . . . . . . . . . . . . . . . . . 4		3.1. Template Variables . . . . . . . . . . . . . . . . . . . . 4
	4.1 Template Variables . . . . . . . . . . . . . . . . . . . . 4		3.2. URI Template Substitution . . . . . . . . . . . . . . . . . 4
	4.2 URI Template Substitution . . . . . . . . . . . . . . . . 4		3.3. Using URI Templates . . . . . . . . . . . . . . . . . . . . 5
	4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5		3.3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 5
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 6		4. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
	7. Normative References . . . . . . . . . . . . . . . . . . . . . 7		6. Normative References . . . . . . . . . . . . . . . . . . . . . 7
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 7		Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 7
	A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 8		Appendix B. Revision History . . . . . . . . . . . . . . . . . . . 7
	B. Revision History . . . . . . . . . . . . . . . . . . . . . . . 8		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7
	Intellectual Property and Copyright Statements . . . . . . . . 9		Intellectual Property and Copyright Statements . . . . . . . . . . 9
	1. Introduction		1. Introduction
	URI Templates are strings that contain embedded variables that are		URI Templates are strings that contain embedded variables that are
	transformed into URIs after embedded variables are substituted. This		transformed into URIs after embedded variables are substituted.
	document defines the structure and syntax of URI Templates.
	URI Templates are useful when it's necessary to convey the structure		This is useful when it's necessary to convey the structure of a URI
	of a URI in a well-defined way. For example, documentation of an		in a well-defined way. For example, documentation of an interface
	interface exposed by a Web site might use a template to show people		exposed by a Web site might use a template to show people how to find
	how to find information about a user;		information about a user;
	http://www.example.com/users/{userid}		http://www.example.com/users/{userid}
	URI Templates can also be thought of as the basis of a machine-		URI Templates can also be thought of as the basis of a machine-
	readable forms language; by allowing clients to form their own		readable forms language; by allowing clients to form their own
	identifiers based on templates given to them by the URI's authority,		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		it's possible to construct dynamic systems that use more of the URI
	than traditional HTML forms are able to. For example,		than traditional HTML forms are able to. For example,
	http://www.example.org/products/{upc}/buyers?page={page_num}		http://www.example.org/products/{upc}/buyers?page={page_num}
	skipping to change at page 3, line 50		skipping to change at page 3, line 49
	variables are available, how to convey them to clients, and what		variables are available, how to convey them to clients, and what
	their appropriate use is in that context.		their appropriate use is in that context.
	2. Notational Conventions		2. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	document are to be interpreted as described in [RFC2119].		document are to be interpreted as described in [RFC2119].
	This specification uses the Augmented Backus-Naur Form (ABNF)		This specification uses the Augmented Backus-Naur Form (ABNF)
	notation of [RFC2234]. See [RFC3986] for reserved and unreserved		notation of [RFC4234]. See [RFC3986] for the definitions of the URI-
	productions.		reference, reserved, and unreserved rules.
	3. Motivation
	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.
	4. URI Template		3. URI Template
	A URI Template is a sequence of characters that contains one or more		A URI Template is a sequence of characters that contains one or more
	embedded template variables Section 4.1. A URI Template becomes a		embedded template variables, see Section 3.1. A URI Template becomes
	URI when the template variables are substituted with the template		a URI when the template variables are substituted with their values
	variables string values, see Section 4.2. The following shows an		(see Section 3.2). For example:
	example URI Template:
	http://example.com/widgets/{widget_id}		http://example.com/widgets/{widget_id}
	If the value of the widget_id variable is "xyzzy", the resulting URI		If the value of the widget_id variable is "xyzzy", the resulting URI
	after substitution is:		after substitution is:
	http://example.com/widgets/xyzzy		http://example.com/widgets/xyzzy
	4.1 Template Variables		3.1. Template Variables
	Template variables are the parameterized components of a URI		Template variables are the parameterized components of a URI
	Template, their representation is described below. A template		Template. A template variable MUST match the template-var rule.
	variable MUST match the template-var production.
	template-char = unreserved		template-char = unreserved
	template-name = 1*template-char		template-name = 1*template-char
	template-var = "{" template-name "}"		template-var = "{" template-name "}"
	4.2 URI Template Substitution		3.2. URI Template Substitution
	Evaluating a URI Template consists of replacing each occurrence of a		Evaluating a URI Template ("substitution") consists of replacing all
	template variable with the string value of that variable. Obtaining		template variables with their respective string values.
	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.
	If the value of a template variable would conflict with a reserved		During substitution, the string value of a template variable MUST
	character's purpose as a delimiter, then the conflicting data must be		have any characters that do not match the reserved or unreserved
	percent-encoded before substitution. That is, merely doing rote		rules (i.e., those characters not legal in URIs without percent
	substitution on template variables could result in the generation of		encoding) percent-encoded, as per [RFC3986], section 2.1. Specific
	an invalid URI for a particular scheme. Specifications that use URI		applications of URI Templates MAY specify additional constraints and
	Templates are expected to take this into consideration in how they		encoding rules in addition to this.
	use such templates.
	When the values of any template variables have been substituted into		Any number of template variables MAY appear in a URI Template; a
	a URI template, the resulting string MUST match the URI-reference		single template-name MAY appear multiple times.
	production of RFC 3986 and MUST also match the productions for the
	scheme in the final URI.
	This specification presumes that the value of a template variable		The result of substitution MUST match the URI-reference rule and
	does not contain characters outside the allowed set for the		SHOULD also match any known rules for the scheme of the resulting
	component(s) of the URI that it parameterizes.		URI.
	4.3 Examples		Typically, this is ensured by the definitions of the template
			variables used. For example, they may specify that a variable's
			value is not to contain certain characters, or that some characters
			should be percent-encoded before substitution.
	Given the following template names and values		3.3. Using URI Templates
	Name Value		Applications using URI Templates will typically need to specify a
	------------------------------------------------------------		number of things, including;
	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
	Note that the name 'wilma' has not been defined, and the value of 'e'		o The template to use.
	is the empty string.		o What template variables are available.
			o For each of the variables;
			* What characters are allowed in the template's value.
			* What encodings should be applied to the value before
			substitutions.
			* How to handle errors such as the output of substitution being
			an invalid URI.
	The following URI Templates will be expanded as shown:		URI Template processors SHOULD allow applications to indicate that;
	http://example.org/{a}/{b}/		o A variable's value is required to contain at least one character
	http://example.org/fred/barney/		o A variable's value is required to match one of a set of supplied
			options
			o A variable's value is to have all reserved characters, as per
			RFC3986, percent-escaped before substitution
	http://example.org/{a}{b}/		Processors MAY make additional options available.
	http://example.org/fredbarney/
			3.3.1. Examples
			Given the following template names and values:
			+--------+--------------------------+
			| Name | Value |
			+--------+--------------------------+
			| a | fred |
			| b | barney |
			| c | cheeseburger |
			| d | one two three |
			| e | 20% tricky |
			| f | |
			| 20 | this-is-spinal-tap |
			| scheme | https |
			| p | quote=to+be+or+not+to+be |
			| q | hullo#world |
			+--------+--------------------------+
			Table 1
			(Note that the name 'wilma' has not been defined, and the value of
			'f' is the empty string.)
			The following URI Templates will be expanded as shown:
	http://example.org/page1#{a}		http://example.org/page1#{a}
	http://example.org/page1#fred		http://example.org/page1#fred
	{scheme}://{20}.example.org?date={wilma}&option={a}		http://example.org/{a}/{b}/
	https://this-is-spinal-tap.example.org?date=&option=fred		http://example.org/fred/barney/
	http://example.org/{a~b}
	http://example.org/none%20of%20the%20above
	http://example.org?{p}		http://example.org/{a}{b}/
	http://example.org?quote=to+bo+or+not+to+be		http://example.org/fredbarney/
	http://example.com/order/{c}/{c}/{c}/		http://example.com/order/{c}/{c}/{c}/
	http://example.com/order/cheeseburger/cheeseburger/cheeseburger/		http://example.com/order/cheeseburger/cheeseburger/cheeseburger/
	http://example.com/{q}		http://example.org/{d}
	http://example.com/hullo#world		http://example.org/one%20two%20three
	http://example.com/{e}/
	http://example.com//
	The following are examples of URI Template expansions that are not		http://example.org/{e}
	legal.		http://example.org/20%25%20tricky
	Name Value		http://example.com/{f}/
	------------------------------------------------------------		http://example.com//
	a fred barney
	b %
	The following URI Templates are expanded with the given values and do		{scheme}://{20}.example.org?date={wilma}&option={a}
	not produce legal URIs.		https://this-is-spinal-tap.example.org?date=&option=fred
	http://example.org/{a}		http://example.org?{p}
	http://example.org/fred barney		http://example.org?quote=to+be+or+not+to+be
	http://example.org/{b}/		http://example.com/{q}
	http://example.org/%/		http://example.com/hullo#world
	5. Security Considerations		4. Security Considerations
	A URI Template does not contain active or executable content. Other		A URI Template does not contain active or executable content. Other
	security considerations are the same as those for URIs, see section 7		security considerations are the same as those for URIs, see section 7
	of RFC3986.		of RFC3986.
	6. IANA Considerations		5. IANA Considerations
	In common with RFC3986, URI scheme names form a registered namespace		In common with RFC3986, URI scheme names form a registered namespace
	that is managed by IANA according to the procedures defined in		that is managed by IANA according to the procedures defined in
	[RFC2717]. No IANA actions are required by this document.		[RFC4395]. No IANA actions are required by this document.
	7. Normative References		6. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119, March 1997.		Requirement Levels", BCP 14, RFC 2119, March 1997.
	[RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
	Specifications: ABNF", RFC 2234, November 1997.
	[RFC2717] Petke, R. and I. King, "Registration Procedures for URL
	Scheme Names", BCP 35, RFC 2717, November 1999.
	[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform		[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
	Resource Identifier (URI): Generic Syntax", STD 66,		Resource Identifier (URI): Generic Syntax", STD 66,
	RFC 3986, January 2005.		RFC 3986, January 2005.
			[RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
			Specifications: ABNF", RFC 4234, October 2005.
			[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
			Registration Procedures for New URI Schemes", BCP 115,
			RFC 4395, February 2006.
	[1] <http://lists.w3.org/Archives/Public/uri/>		[1] <http://lists.w3.org/Archives/Public/uri/>
			Appendix A. Contributors
			The following people made significant contributions to this
			specification: DeWitt Clinton and James Snell.
			Appendix B. Revision History
			01
			00 - Initial Revision.
	Authors' Addresses		Authors' Addresses
	Joe Gregorio (editor)		Joe Gregorio (editor)
	individual
	Email: joe@bitworking.org		Email: joe@bitworking.org
	URI: http://bitworking.org/		URI: http://bitworking.org/
	Marc Hadley (editor)		Marc Hadley (editor)
	Sun Microsystems		Sun Microsystems
	Email: Marc.Hadley@sun.com		Email: Marc.Hadley@sun.com
	URI: http://sun.com/		URI: http://sun.com/
	Mark Nottingham		Mark Nottingham (editor)
	individual
	Email: mnot@pobox.com		Email: mnot@pobox.com
	URI: http://mnot.net/		URI: http://mnot.net/
	David Orchard		David Orchard
	BEA Systems, Inc.		BEA Systems, Inc.
	Email: dorchard@bea.com		Email: dorchard@bea.com
	URI: http://bea.com/		URI: http://bea.com/
	Appendix A. Contributors		Full Copyright Statement
	The following people made significant contributions to this		Copyright (C) The IETF Trust (2007).
	specification: DeWitt Clinton and James Snell.
	Appendix B. Revision History		This document is subject to the rights, licenses and restrictions
			contained in BCP 78, and except as set forth therein, the authors
			retain all their rights.
	00 - Initial Revision.		This document and the information contained herein are provided on an
			"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
			OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
			THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
			OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
			THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
			WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	Intellectual Property Statement		Intellectual Property
	The IETF takes no position regarding the validity or scope of any		The IETF takes no position regarding the validity or scope of any
	Intellectual Property Rights or other rights that might be claimed to		Intellectual Property Rights or other rights that might be claimed to
	pertain to the implementation or use of the technology described in		pertain to the implementation or use of the technology described in
	this document or the extent to which any license under such rights		this document or the extent to which any license under such rights
	might or might not be available; nor does it represent that it has		might or might not be available; nor does it represent that it has
	made any independent effort to identify any such rights. Information		made any independent effort to identify any such rights. Information
	on the procedures with respect to rights in RFC documents can be		on the procedures with respect to rights in RFC documents can be
	found in BCP 78 and BCP 79.		found in BCP 78 and BCP 79.
	skipping to change at page 9, line 29		skipping to change at page 9, line 45
	such proprietary rights by implementers or users of this		such proprietary rights by implementers or users of this
	specification can be obtained from the IETF on-line IPR repository at		specification can be obtained from the IETF on-line IPR repository at
	http://www.ietf.org/ipr.		http://www.ietf.org/ipr.
	The IETF invites any interested party to bring to its attention any		The IETF invites any interested party to bring to its attention any
	copyrights, patents or patent applications, or other proprietary		copyrights, patents or patent applications, or other proprietary
	rights that may cover technology that may be required to implement		rights that may cover technology that may be required to implement
	this standard. Please address the information to the IETF at		this standard. Please address the information to the IETF at
	ietf-ipr@ietf.org.		ietf-ipr@ietf.org.
	The IETF has been notified of intellectual property rights claimed in
	regard to some or all of the specification contained in this
	document. For more information consult the online list of claimed
	rights.
	Disclaimer of Validity
	This document and the information contained herein are provided on an
	"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
	OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
	ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
	INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
	INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
	WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	Copyright Statement
	Copyright (C) The Internet Society (2006). This document is subject
	to the rights, licenses and restrictions contained in BCP 78, and
	except as set forth therein, the authors retain all their rights.
	Acknowledgment		Acknowledgment
	Funding for the RFC Editor function is currently provided by the		Funding for the RFC Editor function is provided by the IETF
	Internet Society.		Administrative Support Activity (IASA).
End of changes. 50 change blocks.
	150 lines changed or deleted		149 lines changed or added
This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/