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

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.