draft-gregorio-uritemplate-02.txt		draft-gregorio-uritemplate-03.txt
	Network Working Group J. Gregorio, Ed.		Network Working Group J. Gregorio, Ed.
	Internet-Draft Google		Internet-Draft Google
	Intended status: Standards Track M. Hadley, Ed.		Intended status: Standards Track M. Hadley, Ed.
	Expires: May 29, 2008 Sun Microsystems		Expires: September 27, 2008 Sun Microsystems
	M. Nottingham, Ed.		M. Nottingham, Ed.
	D. Orchard		D. Orchard
	BEA Systems, Inc.		BEA Systems, Inc.
	Nov 26, 2007		Mar 26, 2008
	URI Template		URI Template
	draft-gregorio-uritemplate-02		draft-gregorio-uritemplate-03
	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 29, 2008.		This Internet-Draft will expire on September 27, 2008.
	Copyright Notice
	Copyright (C) The IETF Trust (2007).
	Abstract		Abstract
	A URI Template is a compact sequence of characters used for the		A URI Template is a compact sequence of characters used for the
	construction of URIs. This specification defines the URI Template		construction of URIs. This specification defines the URI Template
	syntax and the process for expanding a URI Template into a URI, along		syntax and the process for expanding a URI Template into a URI, along
	with guidelines and security considerations for the use of URI		with guidelines and security considerations for the use of URI
	Templates on the Internet. The URI Template syntax allows for the		Templates on the Internet. The URI Template syntax allows for the
	construction of strings that are a superset of URIs, allowing an		construction of strings that are a superset of URIs, allowing an
	implementation to process any URI Template without knowing the		implementation to process any URI Template without knowing the
	skipping to change at page 2, line 20		skipping to change at page 2, line 16
	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
	1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3		1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.2. Design Considerations . . . . . . . . . . . . . . . . . . 4		1.2. Design Considerations . . . . . . . . . . . . . . . . . . 4
	1.3. Notational Conventions . . . . . . . . . . . . . . . . . . 4		1.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 4
	2. Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 4		1.4. Notational Conventions . . . . . . . . . . . . . . . . . . 4
	3. URI Template . . . . . . . . . . . . . . . . . . . . . . . . . 5		2. Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	3.1. Variables . . . . . . . . . . . . . . . . . . . . . . . . 5		3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
	3.2. Template Expansions . . . . . . . . . . . . . . . . . . . 6		4. URI Template . . . . . . . . . . . . . . . . . . . . . . . . . 5
	3.3. URI Template Substitution . . . . . . . . . . . . . . . . 6		4.1. Variables . . . . . . . . . . . . . . . . . . . . . . . . 5
	3.3.1. The 'opt' operator . . . . . . . . . . . . . . . . . . 7		4.2. Template Expansions . . . . . . . . . . . . . . . . . . . 6
	3.3.2. The 'neg' operator . . . . . . . . . . . . . . . . . . 7		4.3. Error Handling . . . . . . . . . . . . . . . . . . . . . . 6
	3.3.3. The 'prefix' operator . . . . . . . . . . . . . . . . 7		4.4. URI Template Substitution . . . . . . . . . . . . . . . . 7
	3.3.4. The 'append' operator . . . . . . . . . . . . . . . . 7		4.4.1. ('var') substitution . . . . . . . . . . . . . . . . . 8
	3.3.5. The 'join' operator . . . . . . . . . . . . . . . . . 7		4.4.2. The 'opt' operator . . . . . . . . . . . . . . . . . . 8
	3.3.6. The 'listjoin' operator . . . . . . . . . . . . . . . 7		4.4.3. The 'neg' operator . . . . . . . . . . . . . . . . . . 8
	3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8		4.4.4. The 'prefix' operator . . . . . . . . . . . . . . . . 9
	4. Security Considerations . . . . . . . . . . . . . . . . . . . 10		4.4.5. The 'suffix' operator . . . . . . . . . . . . . . . . 9
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10		4.4.6. The 'join' operator . . . . . . . . . . . . . . . . . 9
	6. Appendix A - Parsing URI Template Expansions . . . . . . . . . 10		4.4.7. The 'list' operator . . . . . . . . . . . . . . . . . 10
	7. Normative References . . . . . . . . . . . . . . . . . . . . . 11		4.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 11
	Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 11		5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
	Appendix B. Revision History . . . . . . . . . . . . . . . . . . 12		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12		7. Appendix A - Parsing URI Template Expansions . . . . . . . . . 13
	Intellectual Property and Copyright Statements . . . . . . . . . . 13		8. Normative References . . . . . . . . . . . . . . . . . . . . . 13
			Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 14
			Appendix B. Revision History . . . . . . . . . . . . . . . . . . 14
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
			Intellectual Property and Copyright Statements . . . . . . . . . . 16
	1. Introduction		1. Introduction
	A URI Template provides a simple and extensible format for URI		A URI Template provides a simple and extensible format for URI
	construction. A URI Template is a string that contains embedded		construction. A URI Template is a string that contains embedded
	expansions, text marked off in matching braces ('{', '}'), that		expansions, text marked off in matching braces ('{', '}'), that
	denotes a part of the string that is to be substituted by a template		denotes a part of the string that is to be substituted by a template
	processor to produce a URI. A URI Template is transformed into a URI		processor to produce a URI. A URI Template is transformed into a URI
	by substituting the expansions with their calculated value.		by substituting the expansions with their calculated value.
	skipping to change at page 3, line 35		skipping to change at page 3, line 35
	A URI Template allows a structural description of URIs while allowing		A URI Template allows a structural description of URIs while allowing
	a consumer of the template to construct a final URI by providing the		a consumer of the template to construct a final URI by providing the
	values of the expansion variables. For example, given the following		values of the expansion variables. For example, given the following
	URI Template:		URI Template:
	http://www.example.com/users/{userid}		http://www.example.com/users/{userid}
	And the following variable value		And the following variable value
	userid := fred		userid := "fred"
	The expansion of the URI Template is:		The expansion of the URI Template is:
	http://www.example.com/users/fred		http://www.example.com/users/fred
	URI Templates can be used as a machine-readable forms language. By		Here is an example that constructs a query from multiple variables:
	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.
	For example:
	http://www.example.org/products/{upc}/buyers?page={page_num}		http://www.example.com/?{-join|&|query,number}
	URI Templates can also be used to compose URI-centric protocols		And the following variables
	without impinging on authorities' control of their URI space. 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 URI Templates
	allows different sites to specify local ways of conveying the same
	information:
	http://auth.example.com/userauth;{return-uri}		query := "mycelium"
			number := 100
	http://login.example.org/login?back={return-uri}		The expansion of the URI Template is:
			http://www.example.com/?query=mycelium&number=100
			The template expansion describes in a machine readable manner how the
			URI is to be constructed.
			http://www.example.com/?{-join|&|query,number}
			\____________________/
			|
			|
			Join 'var=value' for each variable
			in ['query', 'number'] with '&'.
	1.2. Design Considerations		1.2. Design Considerations
	The URI Template syntax has been designed to carefully balance the		The URI Template syntax has been designed to carefully balance the
	need for a powerful substitution mechanism with ease of		need for a powerful substitution mechanism with ease of
	implementation and security. The syntax is designed to be easy to		implementation and security. The syntax is designed to be easy to
	parse while at the same time providing enough flexibility to express		parse while at the same time providing enough flexibility to express
	many common templating scenarios. On the balance, the template		many common templating scenarios.
	processing is not Turing complete, thus avoiding a number of security
	issues, ala the billion-laughs attack of XML DTDs.
	Another consideration was to keep the syntax and processing in-line		Another consideration was to keep the syntax and processing in-line
	with the pre-existing templating schemes present in OpenSearch, WSDL		with the pre-existing templating schemes present in OpenSearch, WSDL
	and WADL.		and WADL.
	The final design consideration was control over the placement of		The final design consideration was control over the placement of
	reserved characters in the URI generated from a URI Template. The		reserved characters in the URI generated from a URI Template. The
	reserved characters in a URI Template can only appear in the non-		reserved characters in a URI Template can only appear in the non-
	expansion text, or in the argument to an operator, both locations are		expansion text, or in the argument to an operator, both locations are
	dictated by the URI Template author. Given the percent-encoding		dictated by the URI Template author. Given the percent-encoding
	rules for variable values this means that the source of all		rules for variable values this means that the source of all
	structure, i.e reserved characters, in a URI generated from a URI		structure, i.e reserved characters, in a URI generated from a URI
	Template is decided by the URI Template author.		Template is decided by the URI Template author.
	1.3. Notational Conventions		1.3. Applicability
			While URI Templates use a notation that is similar to some URI path
			matching notations in web frameworks, URI Templates were not designed
			for that use case, nor are they appropriate for that purpose. URI
			Templates are not URIs, they do not identify an abstract or physical
			resource, they are not to be treated like URIs, nor should not be
			used in places where a URI would be expected.
			1.4. Notational Conventions
	This specification uses the Augmented Backus-Naur Form (ABNF)		This specification uses the Augmented Backus-Naur Form (ABNF)
	notation of [RFC4234], including the following core ABNF syntax rules		notation of [RFC5234], including the following core ABNF syntax rules
	defined by that specification: ALPHA (letters) and DIGIT (decimal		defined by that specification: ALPHA (letters) and DIGIT (decimal
	digits). See [RFC3986] for the definitions of the URI-reference,		digits). See [RFC3986] for the definitions of the URI-reference,
	percent-encoded, reserved, and unreserved rules.		percent-encoded, reserved, and unreserved rules.
	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].
	2. Characters		2. Characters
	skipping to change at page 5, line 20		skipping to change at page 5, line 29
	character encoding as the surrounding text.		character encoding as the surrounding text.
	The ABNF notation defines its terminal values to be non-negative		The ABNF notation defines its terminal values to be non-negative
	integers (codepoints) based on the US-ASCII coded character set		integers (codepoints) based on the US-ASCII coded character set
	[ASCII]. Because a URI is a sequence of characters, we must invert		[ASCII]. Because a URI is a sequence of characters, we must invert
	that relation in order to understand the URI syntax. Therefore, the		that relation in order to understand the URI syntax. Therefore, the
	integer values used by the ABNF must be mapped back to their		integer values used by the ABNF must be mapped back to their
	corresponding characters via US-ASCII in order to complete the syntax		corresponding characters via US-ASCII in order to complete the syntax
	rules.		rules.
	3. URI Template		3. Terminology
	A URI Template is a sequence of characters that contains one or more		o template processor - A program or library that converts a URI
	embedded template expansions, see Section 3.2. Each expansion		Template into a URI.
	references one or more variables whose values are used in when		o template expansion - The text between '{' and '}', including the
			enclosing brackets.
			4. URI Template
			A URI Template is a sequence of characters that contains any number
			of embedded template expansions, see Section 4.2. Each expansion
			references one or more variables whose values are used when
	determining the substition value for an expansion. A URI Template		determining the substition value for an expansion. A URI Template
	becomes a URI when the template expansions are substituted with their		becomes a URI when all the template expansions are substituted with
	values (see Section 3.3). The generated URI will be a URI-reference,		their values (see Section 4.4). The generated URI will be a URI-
	i.e. either an absolute URI or a relative reference.		reference, i.e. either an absolute URI or a relative reference.
	3.1. Variables		4.1. Variables
	The value of every non-list variable, and the individual values in		Every variable is either a Unicode string or a list of Unicode
	list variables, must come from ( unreserved / pct-encoded ). For		strings.
	variable values that are strings that have characters outside that
	range, the entire string must be converted into UTF-8 [RFC3629], and
	then every octet of the UTF-8 string that falls outside of (
	unreserved / pct-encoded ) MUST be percent-encoded, as per [RFC3986],
	section 2.1.
	This does not imply that every variable value can be decoded into a		A template expansion MAY reference variables that are unknown to the
	Unicode string. For example, a variable value may be a binary blob		template processor. Those variables are 'undefined' and template
	that has been percent-encoded before being passed into the template		expansion takes into consideration 'undefined' variables.
	processor.		Conversely, every variable that he template processor knows about is
			considered 'defined'.
	The Unicode Standard [UNIV4] defines various equivalences between		A variable that contains a string of length zero MUST NOT be
	sequences of characters for various purposes. Unicode Standard Annex		considered 'undefined' by the template processor. A list variable
	#15 [UTR15] defines various Normalization Forms for these		that contains no members, that is of zero length, MUST NOT be
	equivalences, in particular Normalization Form C (NFC, Canonical		considered 'undefined' by the template processor.
	Decomposition, followed by Canonical Composition) and Normalization
	Form KC (NFKC, Compatibility Decomposition, followed by Canonical
	Composition). Since different Normalized Forms unicode strings will
	have different UTF-8 represenations it is RECOMMEDED that unicode
	strings use Normalized Form NFC.
	The meaning of 'defined' for a variable is progamming language and		Beyond the scope of this specification is the allowable programming
	library specific and beyond the scope of this specification. Also		constructs that can be used for a list variable. For example, a
	beyond the scope of this specification is the allowable programming		Python implementation might allow only built-in list types, or it may
	constructs that can be used for a list variable used in the		allow any iterable to be used as the source for a list variable.
	'listjoin' operator. For example, a Python implementation might
	allow only built-in list types, or it may allow any iterable to be		Some variables may be supplied with default values. The default
	used as the source for a list variable.		value must comde from ( unreserved / pct-encoded ). Note that there
			is no notation for supplying default values to list variables.
	A variable may appear in more than one expansion in a URI Template.		A variable may appear in more than one expansion in a URI Template.
	The value used for that variable must remain the same for every		The value used for that variable MUST remain the same for every
	template expansion when converting a URI Template into a URI.		template expansion when converting a URI Template into a URI.
	3.2. Template Expansions		4.2. Template Expansions
	Template expansions are the parameterized components of a URI		Template expansions are the parameterized components of a URI
	Template. A template expansion MUST match the 'expansion' rule.		Template. A template expansion MUST match the 'expansion' rule.
	op = 1*ALPHA		op = 1*ALPHA
	arg = *(reserved / unreserved / pct-encoded)		arg = *(reserved / unreserved / pct-encoded)
	var = varname [ '=' vardefault ]		var = varname [ "=" vardefault ]
	vars = var [ *("," var) ]		vars = var [ *("," var) ]
	varname = (ALPHA / DIGIT)*(ALPHA / DIGIT / "." / "_" / "-" )		varname = (ALPHA / DIGIT)*(ALPHA / DIGIT / "." / "_" / "-" )
	vardefault = *(unreserved / pct-encoded)		vardefault = *(unreserved / pct-encoded)
	operator = "-" op "|" arg "|" vars		operator = "-" op "|" arg "|" vars
	expansion = "{" ( var / operator ) "}"		expansion = "{" ( var / operator ) "}"
	3.3. URI Template Substitution		4.3. Error Handling
			During template substitution error conditions may arise. The exact
			circumstances for those errors are described in Section 4.4. When an
			error occurs the template processor MUST NOT return a URI. It is
			language specific and beyond the scope of this document how the
			template processor signals that an error has occured and that a URI
			will not be generated from the template.
			4.4. URI Template Substitution
	Template substitution is the process of turning a URI Template into a		Template substitution is the process of turning a URI Template into a
	URI given definitions for the variables used in the template.		URI given definitions for the variables used in the template.
	Substitution replaces each expansion with its calculated value.		Substitution replaces each expansion with its calculated value. A
			template processor take two inputs, a URI Template and a set of
			variables, and returns a URI-reference.
	Every expansion consists of either a variable ('var') or an operator		Before substitution the template processor MUST convert every
	expression. In a variable ('var') expansion, if the variable is		variable value into a sequence of characters in ( unreserved / pct-
	defined and non-empty then substitute the value of the variable,		encoded ). The template processor does that using the following
	otherwise substitute the default value. If no default value is given		algorithm: The template processor normalizes the string using NFKC,
	then substitute with the empty string.		converts it to UTF-8 [RFC3629], and then every octet of the UTF-8
			string that falls outside of ( unreserved ) MUST be percent-encoded,
			as per [RFC3986], section 2.1. For variables that are lists, the
			above algorithm is applied to each value in the list.
			The Unicode Standard [UNIV4] defines various equivalences between
			sequences of characters for various purposes. Unicode Standard Annex
			#15 [UTR15] defines various Normalization Forms for these
			equivalences, in particular Normalization Form KC (NFKC,
			Compatibility Decomposition, followed by Canonical Composition).
			Since different Normalized Forms unicode strings will have different
			UTF-8 represenations the only way to guarantee that template
			processors will produce the same URI is to require a common
			Normalized Form.
			Requiring that all characters outside of ( unreserved ) be percent
			encoded means that the only characters outside of ( unreserved ) that
			will appear in the generated URI-reference will come from outside the
			template expansions in the URI Template or from the argument of a
			template expansion. This means that the designer of the URI Template
			determines the placement of reserved characters in the resulting URI,
			and thus the structure of the resulting generated URI-reference.
	If the expansion is an operator then the substitution value is		If the expansion is an operator then the substitution value is
	determined by the given operator. Each operator works only on the		determined by the given operator. Each operator works only on the
	variables that are defined within their expansion.		variables that are defined within their expansion.
	3.3.1. The 'opt' operator		The result of substitution MUST match the URI-reference rule and
			SHOULD also match any known rules for the scheme of the resulting
			URI.
	If the one or more of the variables are defined and non-empty then		If a template processor encounters an operator that it does not
	substitute the value of 'arg', otherwise substitute the empty string.		understand then it MUST fail and MUST NOT produce a URI from the URI
			Template. The list of operators that a template processor knows is
			not constrained by this specification, that is, later specifications
			may add new operators.
	3.3.2. The 'neg' operator		Every expansion consists of either a variable ('var') or an operator
			expression ('operator'), and the rules for how to expand each of
			these is given below. For every expansion a template MUST have at
			least one variable name in the template expansion. It is an error if
			no variables are supplied. All of the variables supplied to a
			template expansion MAY be undefined and the expansion rules below
			specify how to process the template expansion in that situation.
	If all of the variables are un-defined or empty then substitute the		4.4.1. ('var') substitution
			In a variable ('var') expansion, if the variable is defined then
			substitute the value of the variable, otherwise substitute the
			default value. If no default value is given then substitute with the
			empty string.
			Example:
			foo := "fred"
			"{foo}" -> "fred"
			"{bar=wilma}" -> "wilma"
			"{baz}" -> ""
			4.4.2. The 'opt' operator
			If each variable is undefined or an empty list then substitute the
			empty string, otherwise substitute the value of 'arg'.
			Example:
			foo := "fred"
			"{-opt|fred@example.org|foo}" -> "fred@example.org"
			"{-opt|fred@example.org|bar}" -> ""
			4.4.3. The 'neg' operator
			If each variable is undefined or an empty list then substitute the
	value of arg, otherwise substitute the empty string.		value of arg, otherwise substitute the empty string.
	3.3.3. The 'prefix' operator		Example:
	The prefix operator MUST only have one variable in its expansion. If		foo := "fred"
	the variable is defined and non-empty then substitute the value of
	arg followed by the value of the variable, otherwise substitute the
	empty string.
	3.3.4. The 'append' operator		"{-neg|fred@example.org|foo}" -> ""
			"{-neg|fred@example.org|bar}" -> "fred@example.org"
	The append operator MUST only have one variable in its expansion. If		4.4.4. The 'prefix' operator
	the variable is defined and non-empty then substitute the value of
	the variable followed by the value of arg, otherwise substitute the
	empty string.
	3.3.5. The 'join' operator		The prefix operator MUST only have one variable in its expansion.
			More than one variable is an error condition. If the variable is
			undefined or an empty list then substitute the empty string. If the
			variable is a defined non-list then substitute the value of arg
			preceeded by the value of the variable. If the variable is a defined
			list then substitute the concatenation of every list value preceeded
			by the arg.
	For each variable that is defined and non-empty create a keyvalue		Example:
	string that is the concatenation of the variable name, "=", and the
	variable value. Concatenate more than one keyvalue string with
	intervening values of arg to create the substitution value.
	3.3.6. The 'listjoin' operator		foo := "fred"
			bar := ["fee", "fi", "fo", "fum"]
			baz := []
			"{-prefix|/|foo}" -> "/fred"
			"{-prefix|/|bar}" -> "/fee/fi/fo/fum"
			"{-prefix|/|baz}" -> ""
			"{-prefix|/|qux}" -> ""
			4.4.5. The 'suffix' operator
			The prefix operator MUST only have one variable in its expansion.
			More than one variable is an error condition. If the variable is
			undefined or an empty list then substitute the empty string. If the
			variable is a defined non-list then substitute the value of arg
			followed by the value of the variable. If the variable is a defined
			list then substitute the concatenation of every list value followed
			by the arg.
			Example:
			foo := "fred"
			bar := ["fee", "fi", "fo", "fum"]
			baz := []
			"{-suffix|/|foo}" -> "fred/"
			"{-suffix|/|bar}" -> "fee/fi/fo/fum/"
			"{-suffix|/|baz}" -> ""
			"{-suffix|/|qux}" -> ""
			4.4.6. The 'join' operator
			Supplying a list variable to the join operator is an error. For each
			variable that is defined and non-empty create a keyvalue string that
			is the concatenation of the variable name, "=", and the variable
			value. Concatenate more than one keyvalue string with intervening
			values of arg to create the substitution value. The order of
			variables MUST be preserved during substitution.
			Example:
			foo := "fred"
			bar := "barney"
			baz := ""
			"{-join|&|foo,bar,baz,qux}" -> "foo=fred&bar=barney&baz="
			"{-join|&|bar}" -> "bar=barney"
			"{-join|&|qux}" -> ""
			4.4.7. The 'list' operator
	The listjoin operator MUST have only one variable in its expansion		The listjoin operator MUST have only one variable in its expansion
	and that variable must be a list. If the list is non-empty then		and that variable must be a list. More than one variable is an
	substitute the concatenation of all the list members with intevening		error. If the list is non-empty then substitute the concatenation of
	values of arg.		all the list members with intervening values of arg. If the list is
			empty or the variable is undefined them substitute the empty string.
	The result of substitution MUST match the URI-reference rule and		Example:
	SHOULD also match any known rules for the scheme of the resulting
	URI.
	3.4. Examples		foo := ["fred", "barney", "wilma"]
			bar := ["a", "", "c"]
			baz := ["betty"]
			qux := []
			"{-list|/|foo}" -> "fred/barney/wilma"
			"{-list|/|bar}" -> "a//c"
			"{-list|/|baz}" -> "betty"
			"{-list|/|qux}" -> ""
			"{-list|/|corge}" -> ""
			4.5. Examples
	Given the following template variable names and values:		Given the following template variable names and values:
	+----------+--------------------+		+---------+----------------------------------+
	| Name | Value |		| Name | Value |
	+----------+--------------------+		+---------+----------------------------------+
	| a | foo |		| foo | \u03d3 |
	| b | bar |		| bar | fred |
	| data | 10,20,30 |		| baz | 10,20,30 |
	| points | ["10","20", "30"] |		| qux | ["10","20","30"] |
	| list0 | [] |		| corge | [] |
	| str0 | |		| grault | |
	| reserved | :/?#[]@!$&'()*+,;= |		| garply | a/b/c |
	| u | \u2654\u2655 |		| waldo | ben & jerrys |
	| a_b | baz |		| fred | ["fred", "", "wilma"] |
	+----------+--------------------+		| plugh | ["\u017F\u0307", "\u0073\u0307"] |
			| 1-a_b.c | 200 |
			+---------+----------------------------------+
	Table 1		Table 1
	The name 'foo' has not been defined, the value of 'str0' is the empty		The variable 'foo' is the unicode character GREEK UPSILON WITH ACUTE
	string, and both list0 and points are lists. The variable 'u' is a		AND HOOK SYMBOL. This character was chosen because it is one of only
	string of two unicode characters, the WHITE CHESS KING (0x2654) and		three characters that has a different normal form for each of the
	the WHITE CHESS QUEEN (0x2655).		four normalization forms (NFC, NFD, NFKC, NFKD). The name 'xyzzy'
			has not been defined, the value of 'grault' is the empty string. The
			variables qux, corge, fred, and plugh are lists.
	The following URI Templates will be expanded as shown:		The following URI Templates will be expanded as shown:
	----		----
	http://example.org/?q={a}		http://example.org/?q={bar}
	http://example.org/?q=foo		http://example.org/?q=fred
	http://example.org/{foo}
	http://example.org/
	relative/{reserved}/
	relative/%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D/
	http://example.org/{foo=fred}
	http://example.org/fred
	http://example.org/{foo=%25}/
	http://example.org/%25/
	/{-prefix|#|foo}		/{xyzzy}
	/		/
	./{-prefix|#|str0}		http://example.org/?{-join|&|foo,bar,xyzzy,baz}
	./		http://example.org/?foo=%CE%8E&bar=fred&baz=10%2C20%2C30
	/{-append|/|a}{-opt|data|points}{-neg|@|a}{-prefix|#|b}		http://example.org/?d={-list|,|qux}
	/foo/data#bar		http://example.org/?d=10,20,30
	http://example.org/q={u}		http://example.org/?d={-list|&d=|qux}
	http://example.org/q=%E2%99%94%E2%99%95		http://example.org/?d=10&d=20&d=30
	http://example.org/?{-join|&|a,data}		http://example.org/{bar}{bar}/{garply}
	http://example.org/?a=foo&data=10%2C20%2C30		http://example.org/fredfred/a%2Fb%2Fc
	http://example.org/?d={-listjoin|,|points}&{-join|&|a,b}		http://example.org/{bar}{-prefix|/|fred}
	http://example.org/?d=10,20,30&a=foo&b=bar		http://example.org/fred/fred//wilma
	http://example.org/?d={-listjoin|,|list0}&{-join|&|foo}		{-neg|:|corge}{-suffix|:|plugh}
	http://example.org/?d=&		:%E1%B9%A1:%E1%B9%A1:
	http://example.org/?d={-listjoin|&d=|points}		../{waldo}/
	http://example.org/?d=10&d=20&d=30		../ben%20%26%20jerrys/
	http://example.org/{a}{b}/{a_b}		telnet:192.0.2.16{-opt|:80|grault}
	http://example.org/foobar/baz		telnet:192.0.2.16:80
	http://example.org/{a}{-prefix|/-/|a}/		:{1-a_b.c}:
	http://example.org/foo/-/foo/		:200:
	----		----
	4. Security Considerations		5. 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.
	5. IANA Considerations		6. 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
	[RFC4395]. No IANA actions are required by this document.		[RFC4395]. No IANA actions are required by this document.
	6. Appendix A - Parsing URI Template Expansions		7. Appendix A - Parsing URI Template Expansions
	Parsing a valid URI Template expansion does not require building a		Parsing a valid URI Template expansion does not require building a
	parser from the given ABNF. Instead, the set of allowed characters		parser from the given ABNF. Instead, the set of allowed characters
	in each part of URI Template expansion has been chosen to avoid		in each part of URI Template expansion has been chosen to avoid
	complex parsing, and breaking an expansion into its component parts		complex parsing, and breaking an expansion into its component parts
	can be achieved by a series of splits of the character string.		can be achieved by a series of splits of the character string.
	Here is example Python code that parses a URI Template expansion and		Here is example Python code that parses a URI Template expansion and
	returns the operator, argument, and variables as a tuple. The		returns the operator, argument, and variables as a tuple. The
	variables are returned as a dictionary of variable names mapped to		variables are returned as a dictionary of variable names mapped to
	skipping to change at page 11, line 10		skipping to change at page 13, line 44
	return (op, arg, variables)		return (op, arg, variables)
	And here is an example of the parse_expansion() function being used.		And here is an example of the parse_expansion() function being used.
	>>> parse_expansion("-join|&|a,b,c=1")		>>> parse_expansion("-join|&|a,b,c=1")
	('join', '&', {'a': None, 'c': '1', 'b': None})		('join', '&', {'a': None, 'c': '1', 'b': None})
	>>> parse_expansion("c=1")		>>> parse_expansion("c=1")
	(None, None, {'c': '1'})		(None, None, {'c': '1'})
	7. Normative References		8. Normative References
	[ASCII] American National Standards Institute, "Coded Character		[ASCII] American National Standards Institute, "Coded Character
	Set - 7-bit American Standard Code for Information		Set - 7-bit American Standard Code for Information
	Interchange", ANSI X3.4, 1986.		Interchange", ANSI X3.4, 1986.
	[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.
	[RFC2978] Freed, N. and J. Postel, "IANA Charset Registration		[RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
	Procedures", BCP 19, RFC 2978, October 2000.		Procedures", BCP 19, RFC 2978, October 2000.
	[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO		[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
	10646", STD 63, RFC 3629, November 2003.		10646", STD 63, RFC 3629, November 2003.
	[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		[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
	Registration Procedures for New URI Schemes", BCP 115,		Registration Procedures for New URI Schemes", BCP 115,
	RFC 4395, February 2006.		RFC 4395, February 2006.
			[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
			Specifications: ABNF", STD 68, RFC 5234, January 2008.
	[UNIV4] The Unicode Consortium, "The Unicode Standard, Version		[UNIV4] The Unicode Consortium, "The Unicode Standard, Version
	4.0.1, defined by: The Unicode Standard, Version 4.0		4.0.1, defined by: The Unicode Standard, Version 4.0
	(Reading, MA, Addison-Wesley, 2003. ISBN 0-321-18578-1),		(Reading, MA, Addison-Wesley, 2003. ISBN 0-321-18578-1),
	as amended by Unicode 4.0.1		as amended by Unicode 4.0.1
	(http://www.unicode.org/versions/Unicode4.0.1/)",		(http://www.unicode.org/versions/Unicode4.0.1/)",
	March 2004.		March 2004.
	[UTR15] Davis, M. and M. Duerst, "Unicode Normalization Forms",		[UTR15] Davis, M. and M. Duerst, "Unicode Normalization Forms",
	Unicode Standard Annex # 15, April 2003.		Unicode Standard Annex # 15, April 2003.
	[1] <http://lists.w3.org/Archives/Public/uri/>		[1] <http://lists.w3.org/Archives/Public/uri/>
	Appendix A. Contributors		Appendix A. Contributors
	The following people made significant contributions to this		The following people made significant contributions to this
	specification: DeWitt Clinton and James Snell.		specification: Michaeljohn Clement, DeWitt Clinton, John Cowan, James
			H. Manger, and James Snell.
	Appendix B. Revision History		Appendix B. Revision History
			03 - Added more examples. Introduced error conditions and defined
			their handling. Changed listjoin to list. Changed -append to
			-suffix, and allowed -prefix and -suffix to accept list variables.
			Clarified the handling of unicode.
	02 - Added operators and came up with coherent percent-encoding and		02 - Added operators and came up with coherent percent-encoding and
	reserved character story. Added large examples section which is		reserved character story. Added large examples section which is
	extracted and tested against the implementation.		extracted and tested against the implementation.
	01		01
	00 - Initial Revision.		00 - Initial Revision.
	Authors' Addresses		Authors' Addresses
	skipping to change at page 13, line 7		skipping to change at page 16, line 7
	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/
	Full Copyright Statement		Full Copyright Statement
	Copyright (C) The IETF Trust (2007).		Copyright (C) The IETF Trust (2008).
	This document is subject to the rights, licenses and restrictions		This document is subject to the rights, licenses and restrictions
	contained in BCP 78, and except as set forth therein, the authors		contained in BCP 78, and except as set forth therein, the authors
	retain all their rights.		retain all their rights.
	This document and the information contained herein are provided on an		This document and the information contained herein are provided on an
	"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS		"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
	OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND		OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
	THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS		THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
	OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF		OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
	skipping to change at page 13, line 44		skipping to change at line 695
	attempt made to obtain a general license or permission for the use of		attempt made to obtain a general license or permission for the use of
	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.
	Acknowledgment
	Funding for the RFC Editor function is provided by the IETF
	Administrative Support Activity (IASA).
End of changes. 66 change blocks.
	181 lines changed or deleted		316 lines changed or added
This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/