Re: uri-template: optional template parameters?

Hi Eric,

This kind of convention isn't actually used in template processing;  
it's more in line with a "URI Schema Language." I.e., to a template  
processor, the template below has a variable "startPage?" (note the  
question mark's inclusion), and if there's a variable with that name,  
it'll get interpolated; if not, it won't. The same behaviour would be  
seen from a template named "foo", "bar" or  anything else; it's all  
opaque to a generic URI template processor.

This leaves at least two paths forward for your use case;

1) Define the optionality in prose; e.g.,

---8<---
Eric's Foo Template Specification

Eric's Foo Template is a URI Template [reference] in the following form:

   http://example.com/{feedID}/{startPage}

When processing a Foo template, the following variables can be present;
    * startPage: This variable indicates what page to start at; and  
is optional. Its content must be an integer.
    * feedID: The thing variable indicates the thing to get, and is  
required. Its content must be a token.
--->8---

This approach pushes the information about the optionality of the  
variable to its definition; as you can see, you can also put type  
information, etc. there.

2) Define a convention for templates.

When we were working on the URI Templates spec, we wanted to keep it  
as simple as possible, but also recognised that there would be cases  
where it's useful to have conventions for variable naming to handle  
cases like this. If you went this route, you or someone would need to  
define such a convention, which might look something like;

---8<---
Optional Template Convention

When a URI template variable explicitly references this convention,  
it will be considered optional if the last character of the variable  
name is a question mark ("?"). If the last character is not a  
question mark, the variable is required; i.e., it MUST be replaced  
with a non-empty value during template processing.
--->8---

Then, your spec would look something like:

---8<---
Eric's Foo Template Specification

Eric's Foo Template is a URI Template [reference]. All variables use  
the Optional Template Convention [reference]. It is in the following  
form:

   http://example.com/{feedID}/{startPage?}

When processing a Foo template, the following variables can be present;
    * startPage: This variable indicates what page to start at. Its  
content must be an integer.
    * feedID: The thing variable indicates the thing to get. Its  
content must be a token.
--->8---

By using conventions, we don't constrain the syntax of every  
variable; there are enough special cases out there that it would  
quickly make using (and implementing) templates unwieldy.

Make sense?




On 2006/11/14, at 11:09 PM, Eric J. Bowman wrote:

>
> I was wondering what peoples' thoughts are about making template  
> segments
> optional by ending the variable name with a "?", as defined in  
> OpenSearch
> 1.1.  Here's their example:
>
> "http://example.com/feed/{startPage?}"
>
> http://www.opensearch.org/Specifications/OpenSearch/ 
> 1.1#OpenSearch_URL_template_syntax
>
> -Eric
>
>
>
>


--
Mark Nottingham     http://www.mnot.net/

Received on Wednesday, 15 November 2006 16:17:17 UTC