Re: uri-template: optional template parameters?

Another possibility would be to use WADL[1] which allows you to add  
additional metadata to template variables. E.g.

<resources base="http://example.com/">
   <resource path="{feedID}/{startPage}">
     <param style="template" name="feedID" required="true"/>
     <param style="template" name="startPage" required="false"  
type="xsd:int"/>
     ...
   </resource>
</resources>

You can also annotate elements of the description with textual  
descriptions and use XSLT to generate  documentation, Mark has a good  
example of doing this[2].

Marc.

[1] http://wadl.dev.java.net/#spec
[2] http://www.mnot.net/webdesc/

On Nov 15, 2006, at 11:16 AM, Mark Nottingham wrote:

>
> 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/
>
>

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.