Main

Devel

Profiles

PmWiki

Doc archive

Portal

Specification of the URN X-trade, version a.0.1

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.

  • Long form:
$type_of_doc:$ID_params:$description_params:$version
  • Short form:
$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 . . .
Unless noted otherwise, this page is licensed under the Creative Commons Attribution 2.5 License.
Last modification on 2006-Jun-25 at 10:53. Author: feklee