UUID Decoder - RFC 9562

Complete UUID decoder for versions 1-8 as specified in RFC 9562.

📋 Features

• ✅ Full support for UUIDv1 through UUIDv8
• ✅ Extraction of all fields as defined in RFC 9562
• ✅ Timestamp conversion to readable format
• ✅ Reconstruction of fragmented timestamps
• ✅ Multiple output formats (human-readable, JSON, CSV)
• ✅ Simple mode for streamlined output
• ✅ Detailed documentation for each field

🚀 Quick Start

# Human-readable output (default)
python uuid_decoder.py 6ba7b810-9dad-11d1-80b4-00c04fd430c8

# JSON output
python uuid_decoder.py --json 018e8f54-9b85-7a3a-a123-456789abcdef

# Simple JSON (flat structure, no descriptions)
python uuid_decoder.py --simple --json uuid1 uuid2

# CSV output
python uuid_decoder.py --csv uuid1 uuid2 uuid3 > output.csv

📖 Command-Line Options

Basic Usage

python uuid_decoder.py [OPTIONS] <uuid1> [uuid2] [uuid3] ...

Options

Option	Description
--json	Output as JSON format (pipeable to jq)
--simple	Simplified output without descriptions or nested objects
--csv	Output as CSV format
-h, --help	Show help message

Option Combinations

• Default (no options): Human-readable output with all details
• --json: Full JSON with nested structure and descriptions
• --simple --json: Flat JSON structure, essential fields only
• --csv: Flattened CSV format for spreadsheet import

📊 Output Format Examples

1. Human-Readable (Default)

python uuid_decoder.py 018e8f54-9b85-7a3a-a123-456789abcdef

Output:

UUID: 018e8f54-9b85-7a3a-a123-456789abcdef
Version: 7
Variant: RFC 4122/9562
Type: Unix Epoch time-based UUID

--------------------------------------------------------------------------------
DECODED FIELDS:
--------------------------------------------------------------------------------

unix_ts_ms:
  value: 1711801670533
  hex: 0x018e8f549b85
  bits: 0-47
  unix_timestamp: 1711801670.533
  datetime_utc: 2024-03-30T12:27:50.533000+00:00
  datetime_readable: 2024-03-30 12:27:50.533000 UTC
  → Unix timestamp in milliseconds

Entropy bits: 74

2. JSON Output

python uuid_decoder.py --json 018e8f54-9b85-7a3a-a123-456789abcdef

Output:

[
  {
    "uuid": "018e8f54-9b85-7a3a-a123-456789abcdef",
    "version": 7,
    "variant": "RFC 4122/9562",
    "type": "Unix Epoch time-based UUID",
    "fields": {
      "unix_ts_ms": {
        "value": 1711801670533,
        "hex": "0x018e8f549b85",
        "bits": "0-47",
        "unix_timestamp": 1711801670.533,
        "datetime_utc": "2024-03-30T12:27:50.533000+00:00",
        "datetime_readable": "2024-03-30 12:27:50.533000 UTC",
        "description": "Unix timestamp in milliseconds"
      }
    },
    "entropy_bits": 74
  }
]

3. Simple JSON Output

python uuid_decoder.py --simple --json 018e8f54-9b85-7a3a-a123-456789abcdef

Output:

[
  {
    "uuid": "018e8f54-9b85-7a3a-a123-456789abcdef",
    "version": 7,
    "variant": "RFC 4122/9562",
    "unix_ts_ms": 1711801670533,
    "timestamp_unix": 1711801670.533,
    "datetime_utc": "2024-03-30T12:27:50.533000+00:00",
    "datetime_readable": "2024-03-30 12:27:50.533000 UTC",
    "rand_a": 2618,
    "rand_b": 2387828538430180847,
    "entropy_bits": 74
  }
]

Perfect for processing with jq:

python uuid_decoder.py --simple --json uuid1 uuid2 | jq '.[].datetime_readable'

4. CSV Output

python uuid_decoder.py --csv uuid1 uuid2 uuid3 > output.csv

Can be imported directly into Excel, Google Sheets, or any CSV-compatible tool.

📋 Supported UUID Versions

UUIDv1 - Time-based (Gregorian Epoch)

Based on timestamp since October 15, 1582, and MAC address.

Fields:

• time_low, time_mid, time_hi: Timestamp components
• clock_seq: Clock sequence (14 bits)
• node: MAC address (48 bits)
• Reconstructed: datetime_utc, timestamp_unix

UUIDv2 - DCE Security

Similar to v1 with local domain and ID fields.

Fields:

• local_domain: POSIX UID, GID, or ORG
• local_id: Local identifier
• Timestamp and node fields

UUIDv3 - Name-based (MD5)

Deterministic UUID from MD5(namespace + name).

Fields:

• hash_md5: MD5 hash value

UUIDv4 - Random

Completely random with 122 bits of entropy.

Fields:

• random_a, random_b, random_c, random_d: Random components
• entropy_bits: 122

UUIDv5 - Name-based (SHA-1)

Deterministic UUID from SHA-1(namespace + name).

Fields:

• hash_sha1: SHA-1 hash value
• More secure than v3

UUIDv6 - Reordered Time-based

Reordered v1 for lexicographic sorting.

Fields:

• time_high, time_mid, time_low: Reordered timestamp
• clock_seq, node: Same as v1
• Advantage: Natural time-based sorting

UUIDv7 - Unix Timestamp-based

Modern time-based UUID with Unix timestamp.

Fields:

• unix_ts_ms: Unix timestamp in milliseconds
• rand_a, rand_b: Random components (74 bits total)
• Recommended for new projects

UUIDv8 - Custom/Experimental

Customizable format for application-specific needs.

Fields:

• custom_a, custom_b, custom_c, custom_d: Customizable (122 bits)

🎯 Use Cases

1. Debugging

# Check UUID version and timestamp
python uuid_decoder.py <uuid>

2. Data Analysis

# Export multiple UUIDs to CSV for analysis
python uuid_decoder.py --csv uuid1 uuid2 uuid3 > analysis.csv

3. API Integration

# Parse UUID info in scripts
UUID_INFO=$(python uuid_decoder.py --simple --json $UUID)
VERSION=$(echo $UUID_INFO | jq '.[0].version')

4. Timestamp Extraction

# Get creation timestamp from UUIDv1 or UUIDv7
python uuid_decoder.py --simple --json $UUID | jq '.[0].datetime_readable'

🔧 Integration Examples

Bash Script

#!/bin/bash
# Process UUIDs from file
while IFS= read -r uuid; do
    python uuid_decoder.py --simple --json "$uuid"
done < uuids.txt

Python Script

#!/usr/bin/env python3
from uuid_decoder import UUIDDecoder

# Decode UUID
decoder = UUIDDecoder("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
result = decoder.decode(simple=True)

print(f"Version: {result['version']}")
print(f"Timestamp: {result['datetime_readable']}")

JSON Processing

# Extract all timestamps
python uuid_decoder.py --simple --json *.uuid | \
  jq -r '.[] | select(.datetime_utc) | .datetime_utc'

# Filter by version
python uuid_decoder.py --simple --json *.uuid | \
  jq '.[] | select(.version == 7)'

📚 Documentation

• Quick Start Guide - Get started in 5 minutes
• Field Reference - Complete field documentation
• Examples - Generate sample UUIDs

🧪 Testing

# Generate examples
python examples.py

# Test decoder
python uuid_decoder.py --json $(python -c "import uuid; print(uuid.uuid1())")

📄 RFC 9562 Compliance

This decoder is 100% compliant with RFC 9562:

• ✅ All 8 UUID versions supported
• ✅ Exact field names from specification
• ✅ Correct bit-level extraction
• ✅ Proper timestamp reconstruction
• ✅ Accurate epoch handling (Gregorian/Unix)

🚀 Performance

• Fast: Pure Python, no external dependencies
• Memory efficient: Processes UUIDs one at a time
• Batch processing: Handle multiple UUIDs in one command

🔒 Requirements

• Python 3.6+
• No external dependencies (uses only standard library)

📖 References

• RFC 9562 - UUID Specification
• RFC 4122 - UUID URN Namespace
• Python uuid module

📝 License

Public domain - use freely for any purpose.

---

Made with ❤️ for the UUID community