Network Working Group E. Wilde
Internet-Draft C. Davis
Intended status: Standards Track EMC Corporation
Expires: June 10, 2013 Y. Liu
UC Berkeley
December 7, 2012
URI Template Descriptions
draft-wilde-template-desc-00
Abstract
Interactions with many resources on the Web are driven by and/or can
be described by URI Templates. RFC 6570 says that "a URI Template is
a compact sequence of characters for describing a range of Uniform
Resource Identifiers through variable expansion." This specification
defines Template Descriptions, a schema and a media type that can be
used to document and describe a URI Template by supporting
descriptive markup that allows variables to be associated with
documentation (human-oriented) and/or descriptions (machine-
oriented). Template Descriptions can be used by media types (by
inclusion or by reference) that seek to make URI Templates self-
describing, without having to create their own representation.
Note to Readers
Please discuss this draft on the rest-discuss mailing list [9].
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 10, 2013.
Copyright Notice
Wilde, et al. Expires June 10, 2013 [Page 1]
Internet-Draft URI Template Descriptions December 2012
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. URI Template . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Describing Variables . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Template Descriptions . . . . . . . . . . . . . . . . . . . . . 5
3.1. General Concepts . . . . . . . . . . . . . . . . . . . . . 5
3.2. Template Description Structure . . . . . . . . . . . . . . 5
3.3. Variable Description Structure . . . . . . . . . . . . . . 5
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 5
4.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
6.1. OpenSearch . . . . . . . . . . . . . . . . . . . . . . . . 7
6.2. Atom Feeds . . . . . . . . . . . . . . . . . . . . . . . . 7
7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 7
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. Normative References . . . . . . . . . . . . . . . . . . . 8
8.2. Informative References . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8
Wilde, et al. Expires June 10, 2013 [Page 2]
Internet-Draft URI Template Descriptions December 2012
1. Introduction
Simple interactions with resources on the Web often are driven by
simply following links, but in many other cases, interactions with
resources require clients to provide information in addition to just
using a fixed URI in a request. In these cases, information can
provided in any way supported by the interaction protocol, and in
case of HTTP, this often means that information is either embedded in
the URI, and/or in the body of the request. For the first case, the
"URI Template" standard Section 1.1 provides a standard that allows
servers and clients to exchange information about the URIs that a
service accepts.
1.1. URI Template
The "URI Template" standard RFC 6570 [1] specifies "a compact
sequence of characters for describing a range of Uniform Resource
Identifiers through variable expansion." It allows servers to
publish their expectation how a URI should be created by substituting
variables with values. Consider the following URI Template:
http://www.example.com/feed{?pagesize,page}
This URI Template allows clients to expand two variables to end up
with a concrete URI such as the following:
http://www.example.com/feed?pagesize=10&page=42
URI Templates cover the aspect of starting with a template with
variables in it, assigning values to these variables, and then
expanding the template into a URI that can be used for sending a
request. URI Templates make no assumptions or statements about the
value range of the variables, except for those aspects which are
required to cover the process of expanding the template. In
particular, for the example given above, there is no indication that
the values are supposed to be positive integers (the simple data
type), nor is there any indication that the service may apply certain
limits such as a maximum page size (which may change depending on
which paged resource is being accessed). As a side note, even if
this information was known, URI template expansion could still result
in URIs that would not yield successful requests, such as when asking
for a page that is beyond the number of pages that a feed has (in a
given page size).
The goal of Templates Descriptions as defined here is to allow
servers to expose a description resource that provides support both
at development time (when a developer looks at a media type that uses
URI Templates) and at runtime (when a client wants to use a URI
template as part of its application flow).
Wilde, et al. Expires June 10, 2013 [Page 3]
Internet-Draft URI Template Descriptions December 2012
1.2. Describing Variables
Variables can be described in a variety of ways when using Template
Descriptions. For each variable in the URI Template, it is possible
to use the following description methods:
Domain Concept: It is possible to associate a variable with a
domain concept, so that media types and applications can make an
association between the concepts they are defining/exposing, and
where they are represented in URI Tenplates. Concepts can be
referred to by URI, or by using a QName [2].
Datatype: Variables can be described in terms of using certain
datatypes, and the datatype vocabulary is that of XML Schema Part
2 [3], plus all of the applicable facets of those datatypes. This
allows Template Descriptions to constrain the set of allowed
values.
Documentation: Documentation constructs can be associated with
variables, which allows Template Descriptions to attach human-
readable information to individual variables. The documentation
constructs use the documentation design of XML Schema Part 1 [4].
Application Information: Application information constructs can be
associated with variables, which allows Template Descriptions to
attach machine-readable information to individual variables. The
application information constructs use the application information
design of XML Schema Part 1 [4].
For the purpose of this specification, the term "description" should
be interpreted loosely. Some aspects of descriptions can be formal,
such as the datatypes of variables. Thus, such a description can be
used to drive general-purpose logic that knows nothing but this
specification. However, for most other description aspects (domain
concepts, documentation, and application information), this
specification does not prescribe a description framework; it simply
provides a structure how to deliver these descriptions.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [5].
Wilde, et al. Expires June 10, 2013 [Page 4]
Internet-Draft URI Template Descriptions December 2012
3. Template Descriptions
Template Descriptions are based on a URI Template, and add
descriptive elements that allow publishers of URI Templates to
describe the URI Template as a whole, and to add individual
descriptions of all variables in the template.
3.1. General Concepts
As mentioned in Section 1.1, most of the descriptions in this spec to
not prescribe a specific description framework. While variables
(Section 3.3) can be described with a built-in vocabulary of
datatypes, most other descriptions are either for human consumption,
or do rely on some external description framework. To attach these
descriptions to both the template as a whole, and individual
variables, this specification reuses the "appinfo" and
"documentation" elements from XML Schema Part 1 [4]. These elements
carry a "source" attribute which is used (quoting from [4]) "to
supplement the local information."
3.2. Template Description Structure
A template is described by including the URI Template itself, and
optionally adding documentation and/or appinfo elements to add human-
or machine-readable descriptions.
3.3. Variable Description Structure
A variable is described by specifying the variable name. Variables
can refer to a "concept" associated with a variable, which can by
identified by URI, or by a QName (at most one of these SHALL be
present). This specification makes no provision how such a concept
is defined or described, but it allows consumers of a Template
Description to match their understanding of certain concepts to those
identifiers, which then establishes a binding between the concept,
and the variable it has been bound to.
Variable descriptions can optionally add documentation and/or appinfo
elements to add human- or machine-readable descriptions.
4. IANA Considerations
4.1. Media Type
The Internet media type for a Template Description document is
application/td+xml.
Wilde, et al. Expires June 10, 2013 [Page 5]
Internet-Draft URI Template Descriptions December 2012
Type name: application
Subtype name: td+xml
Required parameters: none
Optional parameters: none
Encoding considerations: binary
Security considerations: See Security Considerations in Section 5.
Interoperability considerations: N/A
Published specification: [[ This document ]]
Applications that use this media type: Applications that publish
descriptions of URI Templates.
Additional information:
Magic number(s): N/A
File extension(s): .tdx
Macintosh file type code(s): TEXT
Person & email address to contact for further information: Erik
Wilde <erik.wilde@emc.com>
Intended usage: COMMON
Restrictions on usage: none
Author: Erik Wilde <erik.wilde@emc.com>
Change controller: IETF
4.2. Link Relation
The link relation type below will be registered by IANA per Section
6.2.1 of RFC 5988 [6]:
Relation Name: query-template
Description: Linking to a resource that can be used as a template
description for creating a request URI for the context resource.
Wilde, et al. Expires June 10, 2013 [Page 6]
Internet-Draft URI Template Descriptions December 2012
Reference: [[ This document ]]
Notes: Template Descriptions can be used in all scenarios where
clients want to create requests that represent a query into the
context resource. The media type of the context resource and the
media type of the template description resource are not
constrained by this specification.
5. Security Considerations
...
6. Examples
...
6.1. OpenSearch
...
6.2. Atom Feeds
...
"Feed Paging and Archiving" specified in RFC 5005 [8]
Maybe suggest to use profiles?
7. Open Issues
If and how to use profiles (example in Section 6); if profile use
is recommended, define a suggested profile URI for other specs to
use?
Should we support other ways how URIs could be generated, most
importantly the application/x-www-form-urlencoded method of HTML
forms?
How to handle variables in Level 4 templates that are supposed to
have composite values?
Should there be some way how default values can be exposed/
documented?
Wilde, et al. Expires June 10, 2013 [Page 7]
Internet-Draft URI Template Descriptions December 2012
If a template is refined in an incremental process, does it make
sense to be able to add a "back" link and/or "home" link, so that
clients can find the "most general" version easily?
8. References
8.1. Normative References
[1] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D.
Orchard, "URI Template", RFC 6570, March 2012.
[2] Hollander, D., Layman, A., Thompson, H., Tobin, R., and T. Bray,
"Namespaces in XML 1.0 (Third Edition)", World Wide Web
Consortium Recommendation REC-xml-names-20091208, December 2009,
<http://www.w3.org/TR/2009/REC-xml-names-20091208>.
[3] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Second
Edition", World Wide Web Consortium Recommendation REC-
xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[4] Thompson, H., Beech, D., Mendelsohn, N., and M. Maloney, "XML
Schema Part 1: Structures Second Edition", World Wide Web
Consortium Recommendation REC-xmlschema-1-20041028,
October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>.
[5] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997.
[6] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[7] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication
Format", RFC 4287, December 2005.
8.2. Informative References
[8] Nottingham, M., "Feed Paging and Archiving", RFC 5005,
September 2007.
URIs
[9] <http://tech.groups.yahoo.com/group/rest-discuss/>
Wilde, et al. Expires June 10, 2013 [Page 8]
Internet-Draft URI Template Descriptions December 2012
Authors' Addresses
Erik Wilde
EMC Corporation
6801 Koll Center Parkway
Pleasanton, CA 94566
U.S.A.
Phone: +1-925-6006244
Email: erik.wilde@emc.com
URI: http://dret.net/netdret/
Cornelia Davis
EMC Corporation
Email: cornelia.davis@emc.com
Yiming Liu
UC Berkeley
South Hall
Berkeley, CA 94720
U.S.A.
Email: yliu@ischool.berkeley.edu
Wilde, et al. Expires June 10, 2013 [Page 9]
