URI Template
Extracted elements (29)
Operator characters were chosen to match their roles as reserved characters in URI generic syntax (".", "/", ";", "?", "&", "#"), so the single-character operators correspond to the delimiter they introduce. This makes Level 1-3 templates readable without knowing the spec.
Prefix modifiers count Unicode code points (not octets) to avoid splitting multi-octet UTF-8 sequences or pct-encoded triplets that represent a single code point. This ensures the truncated value is always a valid Unicode string.
The operator characters "=", ",", "!", "@", and "|" are reserved for future extensions and not currently defined. The "$" and "()" characters are explicitly excluded from operator use so that macro languages can apply macro substitution to a string before it is processed as a URI Template.
The specification defines Level 1 as the default simple string expansion (no operator, single variable) to maintain compatibility with prior implementations in WSDL, WADL, and OpenSearch that only implemented this default type. Level 2-4 features are additive extensions.
URI Templates include composite-value operators (explode, named parameters) to describe how resource identifiers are commonly allocated, not merely to generate URIs from changed values. This allows templates to serve as machine-readable structural descriptions of URI spaces.
A URI Template is also an IRI template because the template string may contain the broader set of IRI characters. The result of template processing can be transformed to an IRI by following the process in RFC 3987 Section 3.2.
URI Templates are not URIs: they do not identify a resource, are not parsed as URIs, and SHOULD NOT be used where a URI is expected unless the template will be expanded prior to use. Distinct field, element, or attribute names should differentiate protocol elements carrying a URI Template from those expecting a URI reference.
Variable matching (using a template in reverse to extract variable values from a formed URI) only works reliably when template expressions are delimited by the beginning/end of the URI or by characters that cannot be part of the expansion. In general, regular expression languages are better suited for variable matching.
A template processor limited to lower-level templates MAY exclude ABNF rules for higher levels, but it is RECOMMENDED that all parsers implement the full Level 4 syntax so that unsupported levels can be properly identified to the end user.
Each variable's value MUST be formed prior to template expansion. The expansion process scans the template left-to-right, copying literals and replacing each expression with its expansion.
If a template processor encounters a character sequence outside an expression that does not match the URI-Template grammar, processing SHOULD cease, the result SHOULD contain the expanded part followed by the remainder unexpanded, and the error SHOULD be indicated to the invoking application.
If a value is provided by a user (e.g., via data-entry), the string SHOULD be normalized as NFC (Normalization Form C: Canonical Decomposition followed by Canonical Composition) prior to being used in expansions by a template processor.
If a variable appears more than once in an expression or within multiple expressions of a URI Template, the value of that variable MUST remain static throughout the expansion process.
If an error is encountered inside an expression (unknown operator, unsupported modifier, disallowed character), the unprocessed parts SHOULD be copied to the result unexpanded, processing of the remainder of the template SHOULD continue, and the error location and type SHOULD be indicated to the invoking application.
In all expression types except reserved ("+") and fragment ("#"), a value character of "%" MUST be pct-encoded as "%25" by variable expansion. Reserved and fragment expansions allow "%" as part of pct-encoded triplets to pass through unencoded.
When non-ASCII data is pct-encoded for use in a URI reference, a template processor MUST first encode the string as UTF-8 and then pct-encode any octets not allowed in a URI reference.
A URI Template is a string of printable Unicode characters containing zero or more embedded variable expressions, each delimited by matching braces ('{', '}'). The grammar is: URI-Template = *( literals / expression ). Expressions contain an optional operator followed by a comma-separated variable-list.
An undefined variable (value is null/undef, or a list/associative array with zero members) is ignored by expansion: if all variables in an expression are undefined, the expression's expansion is the empty string. A zero-length string is defined, not undefined.
Form-style query continuation ("&" operator) is used when the template already contains a literal query component with fixed parameters; it appends "&name=value" pairs for each defined variable. This contrasts with "?" which begins a new query component.
Path-style parameter expansion (";" operator) appends ";varname" and omits "=" when the variable value is empty. Form-style query expansion ("?" operator) always appends "=" even when the value is empty, following HTML form conventions.
Reserved expansion ("+" operator) and fragment expansion ("#" operator) allow the union of (unreserved / reserved / pct-encoded) characters to pass through without pct-encoding. All other operators allow only unreserved characters through without pct-encoding.
The operator table (Appendix A) defines per-operator behavior: first (string prepended if any variable is defined), sep (separator between expansions), named (whether to include varname), ifemp (appended when value is empty), and allow (U = unreserved only; U+R = unreserved+reserved+pct-encoded).
If an attacker controls the URI Template itself or controls variable values used with an expression type that allows reserved characters ("+ " or "#"), unanticipated URIs may be crafted. Security depends on who provides the template and values, in what execution context expansion occurs, and where the resulting URIs are used.
In client-side implementations, care ought to be taken to ensure that potentially dangerous URI reference strings such as those beginning with "javascript:" do not appear in the expansion unless both the template and the values are provided by a trusted source. URI Templates in this context have properties similar to HTML forms.
A prefix modifier has the form ":" max-length where max-length = %x31-39 0*3DIGIT (a positive integer less than 10000). The max-length counts Unicode code points from the beginning of the variable's decoded value string, not octets.
An expression has the form "{" [ operator ] variable-list "}". Operators are: op-level2 = "+" / "#"; op-level3 = "." / "/" / ";" / "?" / "&"; op-reserve = "=" / "," / "!" / "@" / "|". Absence of an operator means simple string expansion.
Literals are defined as any Unicode character except CTL, SP, DQUOTE, "'", unencoded "%", "<", ">", "\\", "^", "`", "{", "|", "}". Characters not allowed in URI syntax are copied as their UTF-8 pct-encoded sequences.
The explode modifier is the single character "*" appended to a varspec. It signals that the variable should be treated as a composite value (list or associative array) and each member expanded as if it were a separate variable.
Variable names (varname) are defined as: varname = varchar *( ["."] varchar ); varchar = ALPHA / DIGIT / "_" / pct-encoded. Variable names are case-sensitive. Pct-encoded triplets within a varname are not decoded and are treated as part of the name.