Subject: [Uri-review] Second draft, "tomtomhome" URI scheme

From: "Michiel Salters" <[email-masked]>
Date: Fri, 11 May 2007 17:45:31 +0200

Hi,

based on the feedback of Martin Duerst (thanks!) I've rewritten the
proposal more in
terms of resources. Still, I'm somewhat limited here, as I'm trying to
document what
has been implemented in TomTOm HOME as opposed to what we will
implement.

Again, feedback is welcome.

Michiel.

--- Second draft ---

   URI scheme name: tomtomhome
      
   Status: Provisional

   URI scheme syntax:
	ABNF rules refered but not mentioned here are per RFC-3986 and
RFC-2616
	hier-part = ["//" authority "/"] command-list
	authority = ""
	scheme = "tomtomhome"
	command-list = command "?" query [ ";" command-list ]
	command = "install" / "address" / "location" / "navigateto"
	        / "showonmap" / "addfavourite" / "execute"
	        / *(unreserved)
	query = argument *("&" argument)
	argument = http-url / city / street / housenumber
	         / longitude-latitude 
	         / *(unreserved / escaped / unwise)
	city = *(unreserved / escaped)
	street = *(unreserved / escaped)
	housenumber = *digit
	longitude-latitude = longitude "," latitude
	longitude = [-] 1*digit ["." 1*digit] ["E" / "W"]
	latitude  = [-] 1*digit ["." 1*digit] ["N" / "S"]
	
   Justification:
	This registration documents the URI scheme as implemented by
TomTom
	HOME, a commercial product of TomTom International B.V. (The
Netherlands)
	TomTom HOME implements the consumer side of this interface.
	This scheme was not created with the intent of being specific to
one
	resource type; instead it is specific to TomToms implementation
	of multiple resource types. Hence, the scheme name is
intentionally
	spelled using the TomTom trademark.
   
	<path-absolute> specifies the possible resources encoded by
	such URIs. 

	We allow an empty authority initially to allow for
	non-TomTom <operation>s later on which would obviously need an
	non-empty authority. Plus, experience has shown this is
	better supported in todays Webbrowsers. [If used, violates
	RFC4395 Section 2.2]

	These URIs identify a heterogeneous collection of resources.
	The set of operations on them varies. To distinguish the
	different types, a resource uses the <command> element.
	
	These URIs supports composite resources, where each component
	could be identified by a URI as well. This is achieved by 
	concatenation of the <command> "?" <query> parts. The separator
	used is ";" (Historical implementation note: TomTom HOME 
	versions up to 1.5.106 used "#" in violation of URI guidelines)
	
	Currently the "execute" <operation> serves to indicate that the
	identified document, despite having MIME type text/plain, is a
	list of <command-list>'s, one per line. This <operation> will be
	deprecated when an appropriate MIME type is registered. 
	
URI scheme semantics
	A tomtomhome: URI either is a simple (single) resource
	or a composite resource which can be split in a list of 
	simple resources. Each simple resource has an operation
	(<command>) and arguments for that operation (<query>) 
	defined. The interpretation of a composite resource
	is a simple sequential execution of operations on component
	resources, where a failure of one operation stops the 
	processing of the rest.

	All operations have requirements on their arguments, both on
	the number and content. If these aren't met, the operation
	fails directly.

	An Installable Item resource is described by a TOC (Table Of
	Content) document. The Install operation defined for this
	resource type has one argument, a HTTP resource pointing
	to such a TOC document. Execution of the Install operation
	can be implemented by performing a GET of the TOC document
	and following the instructions in the TOC document: obtain
	the archive(s) referenced by the TOC, extracting the files
	from them, and installing those files.
	(Note: TOC files are created by TomTom HOME, when it creates
	an Installable Item resource from content present on a TomTom
	device)

	An address resource (in the TomTom HOME sense) consists of three
	parts: city, street and housenumber. If an address is suitable
for
	all kind of operations, this URI scheme therefore uses the
generic
	"address" <operation> with arguments city, street and
housenumber 
	(in that order)
	Note: This obviously doesn't cover all possible addresses. In
	particular, it doesn't cover postal addresses. However, this
	form has been succesfully used for (car) navigation purposes. 

	A geographical location (in the TomTom HOME sense) is an
optionally
	named point on the globe. If such a location resource is
suitable
	for all kind of operations, this URI scheme therefore uses the
	generic "location" <operation> with one or two arguments. In
both
	forms, the first argument is a <longitude-latitude> pair. 
	The second argument, where present, is the optional name.
	The numbers are interpreted as degrees with an optional
	decimal fraction. Longitude is East or West of Greenwich,
depending
	on the suffix. If no suffix is present, East is assumed. If a -
sign
	is used, no suffix should be present and the point is in the
western
	hemisphere. Latitude is similar, except it's relative to the
equator,
	North is assumed, and negative longitudes are South of the
equator.
	(The sign convention is thus Cartesian)
	
	The "navigateto" <operation> is used when operations on an
address or
	location resource should be restricted to travel-like operations

	that require a destination. (Note: when used as part of a
composite
	resource, this may be interpreted as an intermediate destination
/ 
	waypoint)

	The "showonmap" <operation> is used when an address or location 
	resource should be interpreted as identifying a position on a
	map (as opposed to a an actual point on the globe)

	The "addfavourite" <operation> is used when an address 
	or location	resource is suitable for inclusion in address
books etc.
	This <operation> takes two or four arguments. The first argument
	is the name of the address or location resource, under which it
may
	be filed in the address book. The name is a free-format	text
argument.
	In the 2-argument form, the second argument is a location;
	in the 4-argument form it is an address. Note that this
operations
	only works on named resources. 

	Indirect resource identification is possible via the "execute"
	<operation>. It takes one argument, an HTTP URL. If an HTTP GET
of that
	URL returns a document with text/plain MIME type, each line of
	that document is interpreted as a <command-list> (i.e. a
composite
	resource). This may be used to encode long address lists.

Encoding considerations
UTF-8, escaped as needed, per RFC-3986 Section 2.5

   Applications/protocols that use this URI scheme name.

TomTom HOME, version 1.5 and later.
TomTom HOME is an application for the management of Portable Navigation
Devices (PND) sold by TomTom. TomTom HOME is included in the purchase,
but
can also be downloaded for free from http://www.tomtom.com/home

The webserver http://addto.tomtom.com/ will redirect to tomtomhome:
URIs. The path and query used in the http URI will be rewritten as
the <command-list> in the tomtomhome URI.

   Interoperability considerations.
      
TomTom is not aware of any interoperable application or
any party trying to become so. We do expect people to use
icnlude http://addto.tomtom.com/ URIs on webpages. 
Patents are pending on the implementation and interpretation of
these URIs in relation to navigation devices. Creation of these
URIs with a goal of making resources available to TomTom HOME
is allowed.

The possibility of other applications to create a tomtomhome URI
should not be used to suggest endorsement of that application by TomTom.

Applications should consider addresses in a fuzzy way, ignoring case
and diacritics. Also, there may be multiple ways of naming a city,
depending on many factors including political. City names do not
appear in isolation; streetnames can be used for disambiguation.

The addfavourite operation will accept a longitude/latitude pair,
which typically requires reverse geocoding to store in an address
book.

   Security considerations.

Applications interpreting an install command should validate
the content before being installed. Applications interpreting
an execute command should not try to read the entire document
into memory.

   Contact.
   Tom Tom Int BV
   Michiel Salters ([email-masked])
   Phone: + 31 (0)20 - 8500800
   Fax: +31.208501099
   Rembrandtplein 35
   Amsterdam,  1017 CT
   NL

      Person (including contact information) to contact for further
      information.
   Author/Change controller.
   Tom Tom Int BV
   Michiel Salters ([email-masked])
   Phone: + 31 (0)20 - 8500800
   Fax: +31.208501099
   Rembrandtplein 35
   Amsterdam,  1017 CT
   NL

      Person (including contact information) authorized to change this,
      if a provisional registration.
  Michiel Salters ([email-masked])

   References.

RFC 3986
RFC 4395
RFC 2616

Michiel Salters | Technical Lead, HOME Client | TomTom |
[email-masked] <mailto:[email-masked]> 

This e-mail message contains information which is confidential and may be privileged. It is intended for use by the addressee only. If you are not the intended addressee, we request that you notify the sender immediately and delete or destroy this e-mail message and any attachment(s), without copying, saving, forwarding, disclosing or using its contents in any other way. TomTom N.V., TomTom International BV or any other company belonging to the TomTom group of companies will not be liable for damage relating to the communication by e-mail of data, documents or any other information.

_______________________________________________
Uri-review mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/uri-review

---

From: "Roy T. Fielding" <[email-masked]>
Date: Fri, 11 May 2007 09:11:33 -0700

Embedding commands within a URI is incredibly bad design.  I suggest
you fix the product before it becomes a hazard to itself.

....Roy