= UUID conventions =
[[TOC]]

== General ==

All records in Sahana Eden which shall be shared with other instances or applications must have a '''universally unique identifier''' (UUID).

In Sahana Eden, these record UUIDs must be ASCII strings.

Eden automatically generates a '''UUID''' for each record according to the specifications in RFC4122:

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

All record UUIDs generated by Sahana Eden are strings in '''URN''' notation:
{{{
urn:uuid:a46c1b3b-35c0-44c6-9142-bbe3a013039a
}}}

If a record is imported into Sahana Eden and it already has a UUID, then Eden will retain this UUID as-is (exception: local domain prefix, see below) - without any syntax validation (i.e. no specific UUID schema is required). However, for consistency reasons, we recommend to use URNs.

Some data formats (e.g. PFIF) may require a '''domain prefix''' for a UUID, followed by a slash:
{{{
sahanafoundation.org/urn:uuid:a46c1b3b-35c0-44c6-9142-bbe3a013039a
}}}

- where such a domain prefix is used and it matches the local domain of the importing Sahana instance, it will be removed during import.
- in exports, the transformation stylesheets for formats which require a domain prefix will prepend the local domain to each un-prefixed UUID.
== Mapping ==
We need an agreed set of UUIDs for GIS Data so that we can share data more easily across systems, such as the [PakistanUnionCouncils current Pakistan data]
 * !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