Generating Persistent UUIDs
Version 5 Universally Unique Identifiers (UUIDs)
<UsagePoint>
must be constant (likewise for <LocalTimeParameters>
, <ReadingType>
, <MeterReading>
, etc.). This is necessary so that a user or Third Party can recognize updates and extensions to the data sets from one Green Button file to the next. The identities of these resources (the IDs) are established when the account is created and don’t change over the life of the account.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 function1. 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:
- The UUIDs generated at different times from the same name in the same namespace MUST be equal.
- The UUIDs generated from two different names in the same namespace should be different (with very high probability).
- The UUIDs generated from the same name in two different namespaces should be different (with very high probability).
- 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):
- The value of
M
is5
for version 5. - 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:
- The UsagePointId (identifier of the
<UsagePoint>
) 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.
- 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>
(“mr”) values of this<UsagePoint>
for the “Wh” readings. - readingTypeName = readingTypeWh ⇐ This will be a constant for all Green Button data you make of that
<ReadingType>
. - localTimeParametersName = localTimeParametersPT ⇐ This will be a constant for all Green Button data you make that are in the Pacific Time zone.
- Then generate the corresponding UUIDs by applying SHA-1 to the desired concatenated string:
- 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). - Then, set the values of
M
andN
by binary-AND’ing:M
is the 13th nibble (from the left)N
is the upper 2 bits of 17th nibble (from the left)
- Format the string with the appropriate hyphens as shown in the format, above.
- Generate the bytes of the
- ^ While SHA-1 is technically not secure anymore, for the purpose of creating UUIDs that insecurity is irrelevant because the resultant is truncated (part of the value is deleted) and thus not reversible.