Generating Persistent UUIDs

Developers must generate the UUIDs in accordance with IETF RFC4122 (https://www.ietf.org/rfc/rfc4122.txt).  To make reproducible UUIDs that do not need to be stored, the developer may use a one-way hash based on SHA-1, which is a secure, non-reversible hash function¹.  The construction of the UUID in this way is called version 5 (note the method discussed below allows you to compute them each time; the algorithm for constructing UUIDs is in section 4.3 of the RFC).

The requirements for Version-5 UUIDs are as follows:

1. The UUIDs generated at different times from the same name in the same namespace MUST be equal.
2. The UUIDs generated from two different names in the same namespace should be different (with very high probability).
3. The UUIDs generated from the same name in two different namespaces should be different (with very high probability).
4. If two UUIDs that were generated from names are equal, then they were generated from the same name in the same namespace (with very high probability).

Method to Generate Version-5 UUIDs

This method of generating a UUID combines a scheme, a namespace, and a name to create a universally unique string that can be formed into a UUID.  It is called “version 5” of IETF RFC4122 that allows the creation of a UUID based on three data elements:

• A namespaceUUIDType – more on this, below.
• A namespace – if the type is NameSpace_URL, then an example namespace would be “www.greenbuttonalliance.org” (but you would use your own, like “xyzutility.com”)
• A name – a unique name within the namespace.

For UUIDs, there are four predefined “potentially interesting” name space IDs defined in Appendix C of IETF RFC4122:

• Fully-Qualified Domain Name:
     NameSpace_DNS = 6ba7b810-9dad-11d1-80b4-00c04fd430c8

• Uniform Resource Locator:
     NameSpace_URL = 6ba7b811-9dad-11d1-80b4-00c04fd430c8

• ISO/IEC 9834-3 (ITU-T X.662) Object Identifier:
     NameSpace_OID = 6ba7b812-9dad-11d1-80b4-00c04fd430c8

• ITU-T X.500 Distinguished Name:
     NameSpace_X500 = 6ba7b814-9dad-11d1-80b4-00c04fd430c8

For example: NameSpace_URL allows you to use a URL (uniform resource locator or weblink) for the namespace part (for this type of namespace, the NameSpace_URL value is 6ba7b811-9dad-11d1-80b4-00c04fd430c8)

The Format

The format of the UUID to use for Green Button implementations is:
urn:uuid:xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
(where M and N are defined in the standard and x are hexadecimal digits, with each digit being a nibble of a byte—or half of a byte):

1. The value of M is 5 for version 5.
2. The value of N is the most-significant two bits of that character set to be 0b10 (binary 1 0).

That is, values of 8, 9, a, or b are valid values of hex nibble N.

An example of how to use this scheme:

1. The UsagePointId (identifier of the <UsagePoint>(from ESPI) is used to identify a device that records either energy consumption or generation.  It must remain the same identifier value even if the existing device is replaced.  Therefore, it cannot be based on the device’s asset tag or serial number, since the asset tag or serial number will change if the device (electric meter, electric vehicle, etc.) requires replacement or upgrading.  Because the resulting UsagePointId cannot be reversed, the street_address of the building can be used as the UsagePointId “namespaceUUIDType”.  If the location contains more than one device, an increasing serial value can be appended to the “namespaceUUIDType”.  Any value can be used as the “namespaceUUIDType” if it is repeatable and cannot be changed.
       
2. Then, create the “names” for the persistent UUIDs for use in your Green Button installation:
   • usagePointName = street_address
   • meterReadingName = street_address + “mrWh”  ⇐ This will be a constant for <MeterReading>(from ESPI (“mr”) values of this <UsagePoint>(from ESPI for the “Wh” readings.
   • readingTypeName = readingTypeWh  ⇐ This will be a constant for all Green Button data you make of that <ReadingType>(from ESPI.
   • localTimeParametersName = localTimeParametersPT  ⇐ This will be a constant for all Green Button data you make that are in the Pacific Time zone.
         
3. Then generate the corresponding UUIDs by applying SHA-1 to the desired concatenated string:
   1. Generate the bytes of the UUID = SHA1(namespaceUUIDType + namespace + name) where each term is an ordered sequence of bytes concatenated (note: leave out formatting and separating characters such as the “-” in the namespaceUUIDType).
   2. Then, set the values of M and N by binary-AND’ing:
      • M is the 13th nibble (from the left)
      • N is the upper 2 bits of 17th nibble (from the left)
   3. Format the string with the appropriate hyphens as shown in the format, above.