Generating Persistent UUIDs

The requirements for Version-5 UUIDs are as follows:

1. 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

For UUIDs, there are four predefined “potentially interesting” namespace IDs (namespaceUUIDType) defined in Appendix C of IETF RFC4122 and in 6.6 of RFC9562:

• • 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 (and a nibble is half of a byte: 4 bits).

1. 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. 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.  Just keep in mind:  the UsagePointId must be locally unique to the DataCustodian.  Encoding the UUID obfuscates it, so no account or other personal data can be deduced from the value of the UsagePointId.
          
   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 the 17th nibble (from the left)
      3. Format the string with the appropriate hyphens (“-”) as shown in the format, above.

Example Code for Generating Repeatable UUIDs

We are providing this Repeatable UUID JavaScript code as an example of how a Data Custodian (typically a Utility company offering Green Button outputs) can ensure consistency for UUIDs and ensure that they are always able to be re-generated when needed.  This RepeatableUuid JavaScript class provides methods for generating UUIDs based on a namespace and a name using the UUID version 5 specification.  This ensures that the same input produces the same output each time it is run, enabling repeatability in UUID generation.

JavaScript Example²

Please see the Footnote regarding any and all use of the provided code examples.  The user assumes all responsibility if the examples are used in deployments.  Code is provided here strictly for illustrative purposes.

class RepeatableUuid {
    // The static UUID representing the DNS namespace as defined in the IETF RFCs for UUIDs.
    static NAMESPACE_DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
    // The static UUID representing the URL namespace as defined in the IETF RFCs for UUIDs.
    static NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
    
    // Generates a version-5 UUID, which is based on a namespace-UUID and a name.
    static async uuidV5(namespaceUuid, name) {
        const nameBytes = new TextEncoder().encode(name);
        return await this.nameBasedUuid(namespaceUuid, nameBytes, 5, 'SHA-1');
    }
    
    // This is the core method for generating the UUID, based on the supplied namespace and name.
    // It validates the UUID version and computes the hash.
    static async nameBasedUuid(namespaceUuid, nameBytes, uuidVersion, cryp) {
        if (uuidVersion !== 5) throw new Error("version must be 5");
        const ns = this.parseUuidToBytes(namespaceUuid);
        
        const digest = await this.computeHash(ns, nameBytes, cryp);
        const out = new Uint8Array(16);
        out.set(digest.subarray(0, 16));
        
        // Set version and variant (IETF RFCs)
        out[6] = (out[6] & 0x0F) | (uuidVersion << 4);
        out[8] = (out[8] & 0x3F) | 0x80;
        
        return this.formatUuid(out);
    }
    
    // This parses the UUID string into a Uint8Array of bytes.
    static parseUuidToBytes(uuid) {
        const s = uuid.toLowerCase();
        
        if (s.length !== 36 || s[8] !== '-' || s[13] !== '-' || s[18] !== '-' || s[23] !== '-') {
            throw new Error("Invalid UUID string: " + uuid);
        }
        
        const hex = s.replace(/-/g, "");
        if (hex.length !== 32) throw new Error("Invalid UUID string: " + uuid);
        
        const bytes = new Uint8Array(16);
        for (let i = 0; i < 16; i++) {
            const hi = this.hexVal(hex.charAt(i * 2));
            const lo = this.hexVal(hex.charAt(i * 2 + 1));
            bytes[i] = (hi << 4) | lo;
        }
        return bytes;
    }
    
    // This converts a hexadecimal character to its numeric value.
    static hexVal(c) {
        if (c >= '0' && c <= '9') return c.charCodeAt(0) - '0'.charCodeAt(0);
        if (c >= 'a' && c <= 'f') return 10 + (c.charCodeAt(0) - 'a'.charCodeAt(0));
        throw new Error("Invalid hex: " + c);
    }
    
    // This formats the Uint8Array of bytes into the standard UUID string representation.
    static formatUuid(rawBytes) {
        let formattedString = '';
        for (let i = 0; i < rawBytes.length; i++) {
            if (i === 4 || i === 6 || i === 8 || i === 10) formattedString += '-';
            const interim = rawBytes[i] & 0xFF;
            formattedString += ((interim >>> 4) & 0xF).toString(16);
            formattedString += (interim & 0xF).toString(16);
        }
        return formattedString;
    }
    
    // This computes the cryptographic hash of the namespace and name bytes using the specified 
    //    hash function, which will be SHA-1 because we want a version-5 UUID.
    static async computeHash(ns, nameBytes, cryp) {
        const hashBuffer = await crypto.subtle.digest(cryp, new Uint8Array([...ns, ...nameBytes]));
        return new Uint8Array(hashBuffer);
    }
}

Invocation of the code example

(async () => {

    // The NAMESPACE_IPAL is the namespace that will represent every UUID generated by 
    //    the “Imaginary Power & Light (IPAL)” utility company.
    const NAMESPACE_IPAL = await RepeatableUuid.uuidV5(RepeatableUuid.NAMESPACE_DNS, 
        "imaginary-power-and-light.com");
    console.log("UUID for Imaginary Power & Light (IPAL): " + NAMESPACE_IPAL);
    
    // The NAMESPACE_IPAL is used to generate the UUID for “Electric Meter 0001” at 
    //    this “1234 SAMPLETON RD APT A…” apartment service location.
    const meterElectric0001 = await RepeatableUuid.uuidV5(NAMESPACE_IPAL, 
        "1234 SAMPLETON RD APT A, ATLANTIS DC 20000 -- Electric Meter 0001");
    console.log("UUID for Electric Meter 0001: " + meterElectric0001);
    
    // The NAMESPACE_IPAL is used to generate the UUID for “Natural Gas Meter 0001” at 
    //    this “1234 SAMPLETON RD APT A…” apartment service location.
    const meterGas0001 = await RepeatableUuid.uuidV5(NAMESPACE_IPAL, 
        "1234 SAMPLETON RD APT A, ATLANTIS DC 20000 -- Natural Gas Meter 0001");
    console.log("UUID for Natural Gas Meter 0001: " + meterGas0001);
    
    // The NAMESPACE_IPAL is used to generate the UUID for Customer Account “87654-3210-3001” 
    //    (it is not specific to one service location).
    const customer = await RepeatableUuid.uuidV5(NAMESPACE_IPAL, "87654-3210-3001");
    console.log("UUID for Customer “87654-3210-3001”: " + customer);

})();

Output of the code example

UUID for Imaginary Light & Power (ILAP): f30ad8b1-8eb6-56d9-a95e-aba961ce074f
UUID for Electric Meter 0001: bba37b63-e44f-5643-9679-a288b2d6c4bf
UUID for Natural Gas Meter 0001: f27552bb-a155-5ff9-995a-edb4b330ab4f
UUID for Customer “87654-3210-3001”: d56bcb52-449b-5b60-be38-eb0e9a275b9a