Introduction
This is a specification of a URN namespace for identifying documents related to (small scale) trade on the Internet. Examples for such documents are messages in mailing lists, news groups, bug databases, and web discussion fora.
General structure
A URN, a Uniform Resource Name, is a special form of a URI, a Uniform Resource
Identifier. Each URN has the following structure:
$NSI:$NSS
$NSI is called the name space identifier, and $NSS is called the name space
specific string. Neither $NSI nor $NSS may contain white space.
Name space identifier
The intended name space identifier is "trade". However, as long as this specification is not an open standard, the name space identifier "X-trade" has to be used instead.
Name space specific string
The name space specific string has one of the following structures.
$type_of_doc:$ID_params:$description_params:$version
$type_of_doc:$ID_params:$version
The long form and the short form are equivalent, i.e. they refer to the same document.
One could imagine that this string is extended later, e.g. by some kind of PGP
signature of $ID_params and $description_params, being introduced before
$version.
$type_of_doc
$type_of_doc describes the type of document. It always consists of four
alphanumeric characters. Examples of types:
task
: Description of a task, for example a feature request.
paym
: Description of a payment intent, i.e. how much one wants to pay for the
accomplishment of a certain task.
strt
: Intention to start working on a task. For example, developers are encouraged to
let other developers know that they already started working on a task.
done
: Accomplishment of a task, to be used e.g. by developers.
rate
: Rating of a trade partner for the specified task. The person doing the rating
should, among other things, judge his partner's payment behavior, the quality of his
specifications, or the quality of the solution he provided.
$ID_params
$ID_params is a string consisting of parameters ensuring that the URN is a
unique identifier for the document. Format:
$param1=$value1;$param2=$value";. . .
Each parameter name consists of four alphanumeric characters.
Parameters (only from
and date
are mandatory):
from
: Email address of the person that created the document.
Note that an email address conforming to RFC2822 and which is not in quoted
string form does, among others, not contain the characters ":", ";", "<", and
">".
date
: Day when the document has been created. Format: $YYYY-$MM-$DD where $YYYY is
the year (e.g. 2004), $MM is the month (e.g. 06 for June), and $DD is the day of the month
(e.g. 04). All dates and times used in trade URNs are relative to UTC.
time
: Time of day when the document has been created. Format: $HH-$MM-$SS wher $HH is
the hour (e.g. 22 for 10 pm), $MM is the minute (e.g. 07), and $SS is the second (e.g.
05).
uniq
: An additional string making sure that $ID_params is unique. This
string should not be necessary in many cases, due to the possiblity of fine grained
specification of time.
$description_params
$description_params is a string of parameters describing the document in a
format that is easily readable by machines. Its format is the same as that of
$ID_params, except that there is no restriction on the length of the parameter
names. Different types of documents have different types of parameters:
- $type_of_doc=
task
(only tild
is mandatory):
tild
: Expiration day. The format is the same as that of the ID parameter date
.
tilt
: Expiration time of day. The format is the same as that of the ID parameter
time
.
Note that the actual description of a task is in the document tagged with the
URN. Rationale: Putting the description into the URN would make it too long,
and, also, a URN is not allowed to contain white space.
- $type_of_doc=
paym
(only task_*
, mini
, and curr
are mandatory):
task_from
, task_date
, task_time
, task_uniq
: Identification of the task
that is associated with the payment.
mini
: Minimum amount of payment that the person who provides a solution
is due to receive.
maxi
: Maximum amount of payment. In many cases, one may not specify
this parameter. However, it could come in handy, especially when trying
to kick start the establishment of the usage of the URNs described in
this document. In this case one could say: "If you properly tag your
work, then I'lll pay you 10 additional EUR".
curr
: Currency according to ISO4217, e.g. "EUR" for Euros, or "USD" for
US Dollars.
- $type_of_doc=
strt
(only task_*
and tild
are mandatory):
task_from
, . . .: See $type_of_doc=paym
.
tild
, tilt
: How long work on the task presumably takes. See the parameters of
$type_of_doc=task
for a description of the format.
Note that the above information - as actually all information provided
by the URNs described in this document - is not binding. For
example, a developer who - after looking at rating statistics - knows that
another developer is unreliable, may simply ignore his announcements. In any case:
Whoever finishes earliest, gets the pay, unless his solution does not meet the objectives
of the task.
- $type_of_doc=
done
(only task_*
are mandatory):
task_from
, . . .: See $type_of_doc=paym
.
- $type_of_doc=
rate
:
task_from
, . . .: See $type_of_doc=paym
.
ptnr
: Email address of the trade partner.
rate
: Rating. A floating point number between 0 and 1 where 1 means
total satisfaction with the trade partner, and 0 means absolute disappointment.
$version
For any name space specific strings formatted according to this specification:
$version=a.0.1
$version describes the version of the specification according to which the URN is
formatted. It will always appear at the end, even if more components are
included into the URN structure. The rationale for putting the version at the end
is that in case there ever will be a final standard which will not change
considerably anymore, then one could easily leave $version away.
Tagging a document
For tagging a document, a string of the following format is included into it:
<this-X-trade:$type_of_doc:$ID_params:$description_params:$version>
The string in between the angular brackets can be structured by the use of
white space. This white space has to be removed by a parser prior to
interpretation of the string.
A document may be tagged with more than one trade URN.
Examples:
- Task description with payment:
Anyone who provides a version of EMACS' autofill-mode that supports
automatic line breaking in "this-X-trade" URN tags gets 20 EUR. If, when
corresponding with me, he adheres to the X-trade URN specification version a.0.1
(which due to lack of tools is a bit cumbersome to use), then he'll receive an
additional 10 EUR.
<this-X-trade:task:
from=foo@bar.baz;date=2006-04-09:
tild=2006-04-20:
a.0.1>
<this-X-trade:paym:
from=foo@bar.baz;date=2006-04-09:
task_from=foo@bar.baz;task_date=2006-04-09:
mini=20;maxi=30;curr=EUR:
a.0.1>
Referring to a tagged document
The URN
X-trade:$type_of_doc:$ID_params:$description_params:$version
is, by definition, equivalent to the URN
X-trade:$type_of_doc:$ID_params:$version
This means that when referring to a document, it is not necessary to include
the $description_params into the URN.
For formatting referrals to a trade URNs there are no strict rules, just some
recommendations:
- Embedding the URN in angular brackets makes it easier to identify,
especially when white space is used to structure it visually:
<X-trade:$NSS>
Remember: $NSS is the name space specific string, defined earlier.
- To make humans and machines aware that what they're reading is a URN, one may
prefix it with the string urn (in lower, upper, or mixed case):
<urn:X-trade:$NSS>
Examples:
- Someone announces that a task has been specified somewhere else:
Hey folks,
over in the devel mailing list, I've already announced a task for whose
accomplishment I'll pay between 20 and 30 EUR:
<urn:X-trade:task:
from=foo@bar.baz;date=2006-04-09:
a.0.1>
If anyone is interested . . .