Home

Introduction

URI template is defined by RFC 6570. Unfortunately, the text of the RFC is quite complex to follow, and it takes quite some time to make sense of the different sections and proposed algorithm.

The algorithm used by this implementation is based on the reference algorithm but differs in a fundamental way, so as to make it more simple, therefore easier to implement, and ultimately less bug prone. This implementation is heavily tested and, as far as the author can tell, all you can throw at it will be rendered correctly.

This page sets as a goal to fully explain the algorithm. But before plunging into the core of the matter, a number of definitions must be written so that the algorithm itself be easily understood.

Definitions

Preliminary note

These definitions are a pot-pourri extracted by yours truly (the author of this page) from what the RFC says and what an actual implementation has to deal with.

As such, this is not a one-to-one matching of what you can find in the RFC. In particular, levels defined by the RFC (from 1 to 4) have been deemed counterproductive, and you will find no mention of them in these definitions. If anything, these levels are unusable in any sane implementation, and they are not even referred to in the reference algorithm.

Variable value

A variable value can be either of a string, a list or a map. Note that the RFC refers to maps (ie, key/value pairs) as associative arrays; this text, however, uses maps. All list elements or map keys/values are strings. Examples of variable values are (note: JSON representations):

• "foobar" (string),
• [ "foo", "bar" ] (list),
• { "key1": "foo", "key2": "bar" } (map).

Variable specifier (or varspec for short)

The term "varspec" will be used from now on.

A varspec is an association of a variable name with an optional modifier. Modifers can be of two kinds: the explode modifier (*) or a prefix modifier (:n, where n is an integer between 0 and 10000).

Note: unlike the sample RFC algorithm, this implementation does not allow both modifiers to exist at the same time (which does not make sense anyway).

Examples of varspecs are:

• foobar:12 (variable name foobar, with prefix modifier, length 12);
• foobar* (variable name foobar, with explode modifier).

Expression type

The expression type is determined by the first character found in a template expression (see below). Even though the algorithm is not driven by expression types, they are the most crucial information to be accounted for when expanding:

• the prefix string: what string should be in front of any non empty expansion list;
• the joining character: if the expansion is non empty, what character should be used to join the expansion list elements;
• the raw character set: what characters in a value should not be subjected to percent-encoding expansion;
• the empty value substitution: in some situations, when a given value is empty, this string should be used as a replacement;
• named versus non named: for some expression types, the variable name should be used in order to produce the expanded string.

For those of you who have read the RFC in its entirety, you will recognize here the different expression type criteria; this algorithm uses the same criteria, but uses them differently.

URI template expression

A URI template expression is defined by a sequence of the beginning character of a template ({), followed by an optional expression type character (none means basic expression type), followed by one or more varspecs separated by commas, followed by the end character of a template ('}').

Examples: {var,list,map}; {#foo:3,list*}; and so on.