[[TOC]]
= UUID conventions =

== General ==

UUIDs (Universal Unique IDentifiers) in Eden follow the Python uuid implementation,
which is specified in RFC4122:

    http://www.faqs.org/rfcs/rfc4122.html

However, other systems do not necessarily follow this convention (especially data sets
outside of IT systems), but we still must be able to identify such data resources.

Therefore, in every shared resource (XML+JSON), the UUID shall be prefixed by the domain
name of the originating instance (authoritative domain) plus a slash ("/"), e.g.

{{{
    haiti.sahanafoundation.org/12345678-1234-5678-1234-567812345678
}}}

Generally, a "domain name" here can be any arbitraty XML name except it must not contain
any slashes. However, the domain name must be unique, of course - and therefore it is
recommended to use the internet domain name of the current instance. This in turn requires
that all applications which share that domain name and take part in the data exchange adhere
to the same UUID convention (UUID's have to be unique at least within the same domain).

This convention is adopted from the person_record_id convention of [http://zesty.ca/pfif/1.1/#person-records PFIF].

== Implementation Guideline ==

At '''import''', when the system receives a resource with a prefixed UUID and the prefix matches
the domain of the current instance, then the prefix gets removed to identify the resource
in the database. If the prefix differs from our domain, then the prefix is retained in the
database record.

At '''export''', all unprefixed UUIDs from the database get prefixed by the domain name of the
current instance. In those UUIDs which already have a prefix (because they have been imported
from another domain), the prefix is retained.

== Mapping ==
We need an agreed set of [http://eden.sahanafoundation.org/wiki/UUID UUID]s for GIS Data so that we can share data more easily across systems.
 * !OpenStreetMap IDs can change over time if records are deleted/recreated
  * They can [http://wiki.openstreetmap.org/wiki/Humanitarian_OSM_Tags/Humanitarian_Data_Model#ID hold additional uid/uuid fields] though
 * Geonames data isn't free enough for OSM: http://wiki.openstreetmap.org/wiki/Geonames
  * Geonet can be: http://wiki.openstreetmap.org/wiki/GEOnet_Names_Server
 * Yahoo WoE data is in the public domain:
  * XML: http://code.flickr.com/blog/2009/05/21/flickr-shapefiles-public-dataset-10/
  * Tab: http://developer.yahoo.com/geo/geoplanet/data/
 * Ushahidi doesn't have a common set of IDs across instances
  * No space for a UUID either?
 * Longer-term we need a common central repository of UUIDs that is held for the common good.
  * Propose that Sahana start this off & then give up ownership/branding later:
  * Sahana can use UUIDs of format: http://geo.sahanafoundation.org/<ID>
  * These are associated with an OSM ID & Geonames ID for cross-correlation
  * The Source ID field shows the source, so that OSM export can filter out sources like Geonames
  * IDs from Ushahidi instances can be appended to the comments field in Sahana

----
DeveloperGuidelines