Alphabets

OpaqueId provides flexible alphabet configuration for generating IDs with different character sets. This guide covers built-in alphabets, custom alphabet creation, and best practices for alphabet selection.

• TOC

Built-in Alphabets

OpaqueId comes with two pre-configured alphabets optimized for different use cases.

ALPHANUMERIC_ALPHABET (Default)

The default alphabet provides a good balance of security, readability, and URL safety.

# Characters: A-Z, a-z, 0-9 (62 characters)
# Use case: General purpose, URL-safe
# Example output: "V1StGXR8_Z5jdHi6B-myT"

class User < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET
end

Characteristics:

• Length: 62 characters
• Characters: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789
• URL-safe: Yes (no special characters)
• Human-readable: Yes (no confusing characters)
• Performance: Good (62 characters)

Use cases:

• General purpose ID generation
• Public URLs and user-facing identifiers
• APIs and web services
• Database primary keys

STANDARD_ALPHABET

The standard alphabet provides the fastest generation speed with 64 characters.

# Characters: A-Z, a-z, 0-9, -, _ (64 characters)
# Use case: Fastest generation, URL-safe
# Example output: "V1StGXR8_Z5jdHi6B-myT"

class User < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET
end

Characteristics:

• Length: 64 characters
• Characters: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
• URL-safe: Yes (includes hyphens and underscores)
• Human-readable: Yes (minimal special characters)
• Performance: Best (64 characters, optimized path)

Use cases:

• High-performance applications
• Internal system identifiers
• APIs with high throughput
• Background job systems

Alphabet Comparison

Alphabet	Characters	Length	URL-Safe	Performance	Use Case
ALPHANUMERIC_ALPHABET	A-Z, a-z, 0-9	62	✅	Good	General purpose
STANDARD_ALPHABET	A-Z, a-z, 0-9, -, _	64	✅	Best	High performance

Custom Alphabets

Create custom alphabets for specific requirements and use cases.

Numeric Only

Generate numeric-only IDs for order numbers, invoice numbers, etc.

class Order < ApplicationRecord
  include OpaqueId::Model

  # Generate numeric-only IDs
  self.opaque_id_alphabet = "0123456789"
  self.opaque_id_length = 10
end

# Example output: "1234567890"

Use cases:

• Order numbers
• Invoice numbers
• Reference numbers
• Sequential-looking IDs

Hexadecimal

Generate hexadecimal IDs for API keys, tokens, etc.

class ApiKey < ApplicationRecord
  include OpaqueId::Model

  # Generate hexadecimal IDs
  self.opaque_id_alphabet = "0123456789abcdef"
  self.opaque_id_length = 16
end

# Example output: "a1b2c3d4e5f67890"

Use cases:

• API keys
• Authentication tokens
• Session identifiers
• Cryptographic keys

URL-Safe Characters

Generate IDs with maximum URL safety.

class Article < ApplicationRecord
  include OpaqueId::Model

  # Generate URL-safe IDs
  self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
  self.opaque_id_length = 8
end

# Example output: "V1StGXR8"

Use cases:

• URL slugs
• Public identifiers
• Social media sharing
• Email-friendly IDs

Base64-Style

Generate Base64-style IDs for maximum character diversity.

class Document < ApplicationRecord
  include OpaqueId::Model

  # Generate Base64-style IDs
  self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
  self.opaque_id_length = 12
end

# Example output: "V1StGXR8_Z5j"

Use cases:

• Document identifiers
• File references
• Binary data representation
• High-entropy requirements

Uppercase Only

Generate uppercase-only IDs for better readability.

class Product < ApplicationRecord
  include OpaqueId::Model

  # Generate uppercase-only IDs
  self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
  self.opaque_id_length = 10
end

# Example output: "V1STGXR8Z5"

Use cases:

• Product codes
• SKUs
• License keys
• Human-readable identifiers

Lowercase Only

Generate lowercase-only IDs for consistent formatting.

class User < ApplicationRecord
  include OpaqueId::Model

  # Generate lowercase-only IDs
  self.opaque_id_alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
  self.opaque_id_length = 12
end

# Example output: "v1stgxr8z5jd"

Use cases:

• Usernames
• Subdomains
• File names
• Consistent formatting

No Confusing Characters

Generate IDs without characters that can be easily confused.

class User < ApplicationRecord
  include OpaqueId::Model

  # Exclude confusing characters: 0, O, l, I, 1
  self.opaque_id_alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789"
  self.opaque_id_length = 15
end

# Example output: "V2StGXR8Z5jdHi6B"

Use cases:

• Human-readable IDs
• Voice communication
• Hand-written transcription
• Accessibility

Specialized Characters

Generate IDs with specific character sets for unique requirements.

class Game < ApplicationRecord
  include OpaqueId::Model

  # Game-friendly characters (no vowels to avoid words)
  self.opaque_id_alphabet = "BCDFGHJKLMNPQRSTVWXYZbcdfghjklmnpqrstvwxyz23456789"
  self.opaque_id_length = 8
end

# Example output: "B2StGXR8"

Use cases:

• Game codes
• Room identifiers
• Tournament codes
• Content filtering

Alphabet Selection Guide

Choose by Use Case

Public URLs

# URL-safe, human-readable
self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET

High Performance

# Fastest generation
self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET

Human Readable

# No confusing characters
self.opaque_id_alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789"

Maximum Security

# High entropy, many characters
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*"

Numeric Only

# Numbers only
self.opaque_id_alphabet = "0123456789"

Choose by Length

Short IDs (8-12 characters)

# Use larger alphabets for shorter IDs
self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET
self.opaque_id_length = 8

Medium IDs (15-21 characters)

# Standard alphabets work well
self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET
self.opaque_id_length = 21

Long IDs (32+ characters)

# Any alphabet works, consider performance
self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET
self.opaque_id_length = 32

Performance Considerations

Alphabet Size Impact

Larger alphabets generally provide better performance due to optimized algorithms:

# 64 characters - fastest (optimized path)
self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET

# 62 characters - good performance
self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET

# 16 characters - slower (rejection sampling)
self.opaque_id_alphabet = "0123456789abcdef"

# 10 characters - slowest (rejection sampling)
self.opaque_id_alphabet = "0123456789"

Character Set Optimization

# Optimized for 64 characters
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"

# Good performance with 62 characters
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

# Slower with smaller sets
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"

Security Considerations

Entropy and Security

Larger alphabets provide more entropy per character:

# High entropy (64 characters)
self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET
self.opaque_id_length = 21
# Entropy: 21 * log2(64) = 126 bits

# Medium entropy (62 characters)
self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET
self.opaque_id_length = 21
# Entropy: 21 * log2(62) = 125 bits

# Lower entropy (16 characters)
self.opaque_id_alphabet = "0123456789abcdef"
self.opaque_id_length = 21
# Entropy: 21 * log2(16) = 84 bits

Character Predictability

Avoid predictable character patterns:

# Good - random character distribution
self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET

# Avoid - sequential patterns
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

# Avoid - common patterns
self.opaque_id_alphabet = "0123456789"

Best Practices

1. Choose Appropriate Alphabet Size

• 64 characters: Best performance, good security
• 62 characters: Good balance, URL-safe
• 32 characters: Moderate performance, specific use cases
• 16 characters: Slower, specific requirements
• 10 characters: Slowest, numeric-only needs

2. Consider URL Safety

# URL-safe characters
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"

# Avoid URL-unsafe characters
self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*"

3. Avoid Confusing Characters

# Exclude confusing characters
self.opaque_id_alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789"

# Or use purge_chars option
self.opaque_id_purge_chars = ['0', 'O', 'l', 'I', '1']

4. Test Your Alphabet

# Test alphabet generation
class User < ApplicationRecord
  include OpaqueId::Model

  self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
  self.opaque_id_length = 10
end

# Generate test IDs
5.times { puts User.new.opaque_id }
# => "V1STGXR8Z5"
# => "K8JH2MN9PL"
# => "Q3RT7S1V4X"
# => "B6NF9C2M8Y"
# => "D4HG7K1P5W"

Common Alphabet Patterns

E-commerce

# Order numbers - numeric
class Order < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = "0123456789"
  self.opaque_id_length = 8
end

# Product codes - alphanumeric
class Product < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET
  self.opaque_id_length = 12
end

API Development

# API keys - hexadecimal
class ApiKey < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = "0123456789abcdef"
  self.opaque_id_length = 32
end

# API tokens - standard
class ApiToken < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET
  self.opaque_id_length = 24
end

Content Management

# Article slugs - URL-safe
class Article < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
  self.opaque_id_length = 8
end

# Comments - standard
class Comment < ApplicationRecord
  include OpaqueId::Model
  self.opaque_id_alphabet = OpaqueId::ALPHANUMERIC_ALPHABET
  self.opaque_id_length = 15
end

Next Steps

Now that you understand alphabet configuration:

1. Explore Configuration for complete configuration options
2. Check out Use Cases for real-world alphabet usage
3. Review Performance for alphabet optimization tips
4. Read API Reference for complete alphabet documentation