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

Introduction

This is an early draft for a specification of a URN namespace for identifying documents related to (small scale) trade on the Internet. Examples of 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 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

Suggestion for the name space identifier: "trade".

Name space specific string

The name space specific string, in the present case, has one of the following structures.

• Long form:

• Short form:

The long form and the short form are lexically equivalent.

One could imagine that this is extended later, e.g. by some kind of PGP signature of $ID_params and $description_params, being introduced before $version. Furthermore, at the moment, it is yet unclear how many details of the name space specific string should best be part of this specification.

$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.
• revc: Revocation of a task.
• strt: Intention to start working on a task. Used e.g. by a developer to "check out" the task.
• done: Accomplishment of a task, to be used e.g. by developers.
• rate: Rating of a trade partner, i.e. someone who worked on a task or someone who indended to or did pay for the accomplishment of a task.

$ID_params

$ID_params is a string consisting of parameters ensuring that the URN is a unique identifier for the document. Format:

Each parameter name consists of four alphanumeric characters.

Examples of parameters (not all have to be specified):

• from: Email address of the person that created the document. Note that not everyone may want to disclose his email address in plain text, so there should be an alternative way of identifying the author. Another option could perhaps be a parameter allowing the specification of a PGP fingerprint, or hashing the email address.
  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.
• time: Time of day when the document has been created.
• zone: The time zone. Defaults to GMT.
• uniq: An additional string making sure that $ID_params is unique. This string should not be necessary in most cases.

$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, Examples of parameters (grouped by the document type that they're associated with):

• $type_of_doc="task":
  • tild: Expiration day.
  • tilt: Expiration time of day.
  • zone: Time zone.
  • comp: If the value is "t", then this is an competition, which means that only the person who provides the best solution in the given time frame will get paid. Otherwise, the person who delivers the first solution will get the pay. Of course, the creator of the task URN may later ignore these rules, but that will most likely get him a bad rating e.g. from developers who didn't get the pay they deserved.
  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":
  • task_from, task_date, task_time, ...: 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. Most of the time 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 Dollars.
• $type_of_doc="strt":
  • task_from, task_date, task_time, ...: See $type_of_doc.
  • tild, tilt: How long work on the task probably takes.
  Note that this information is, as actually all information provided by the URNs described in this document, of informational nature. For example, a developer who - after looking at rating statistics - knows that another developer is unreliable, may simply ignore him working on a task, and whoever finishes earliest is supposed to get the pay.
• $type_of_doc="done":
  • task_from, task_date, task_time, ...: See $type_of_doc.
  At first glance, no additional parameters may be necessary.
• $type_of_doc="rate":
  • task_from, task_date, task_time, ...: See $type_of_doc.
  • type: What document one wants to rate. For example, to rate a developer's quality of work one would rate the document tagged with a "done" URN. A developer who wants to rate the specification of a client, or his payment behavior, would rate the document associated with the "task" URN or the "paym" URN.
  • rate: Rating. A floating point number between 0 and 1 where 1 means perfection and 0 means crap.

$version

For any name space specific strings formatted according to this specification:

$version describes the version of the standard according to which the URN is formatted. It will always appear at the end, even if more components are included into the 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:

As we see, in this case usage of the long form of the name space specific string is mandatory.

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-trade" URLs gets 30 EUR. If, when corresponding with me, he adheres to the 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-trade:task:
  from=foo@bar.baz;date=2006-04-09:
  tild=2006-04-20:
  0.1>
  <this-trade:paym:
  from=foo@bar.baz;date=2006-04-09:
  mini=30;maxi=40;curr=EUR>

Referring to a tagged document

The URN

is, by definition, equivalent to the URN

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:
  <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:trade:$NSS>

Examples:

• Someone announces that a task has already specified somewhere else:
  Hey folks,
  over in the devel mailing list, I've already announced a task for whose accomplishment I'll pay between 30 and 40 EUR.
  <this-trade:task:
  from=foo@bar.baz;date=2006-04-09:
  0.1>
  If anyone is interested ...