WDP 5-Part Error Code Structure

Notation Conventions#

This specification uses the following notation conventions throughout:

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Note: This document is non-normative. Normative requirements are defined in the individual specification parts.

What is WDP?#

The Waddling Diagnostic Protocol (WDP) is a structured, cross-language error coding system that provides both human-readable semantic codes and compact machine-friendly identifiers.

The 5-Part Structure#

Every WDP error code consists of five parts:

Severity.Component.Primary.Sequence -> CompactID
    ^         ^        ^        ^          ^
  Part 1    Part 2   Part 3   Part 4    Part 5

Structure Breakdown:

Parts 1-4: Structured Code    |    Part 5: Compact ID
(Human-readable, semantic)    |    (Machine-friendly, efficient)

Complete Example

E.Auth.Token.001 -> Xy8Qz
│ │    │     │      │
│ │    │     │      └─ Part 5: Compact ID (5-char hash)
│ │    │     └──────── Part 4: Sequence (specific event)
│ │    └────────────── Part 3: Primary (failure domain)
│ └─────────────────── Part 2: Component (system module)
└───────────────────── Part 1: Severity (urgency level)

Both representations identify the same error:

• Structured code: E.Auth.Token.001 (for humans, logs, debugging)
• Compact ID: Xy8Qz (for APIs, transmission, databases)

The Five Parts Explained#

Component.Primary
    ↓        ↓
Auth.Token           - Token-related authentication errors
Auth.Session         - Session-related authentication errors
Auth.Permission      - Permission-related authentication errors

Database.Connection  - Database connection errors
Database.Query       - Database query errors
Database.Transaction - Database transaction errors

Canonical Identity: 001, 002, 003 (numeric)
       ↕
Associated Name: TOKEN_MISSING, TOKEN_EXPIRED (semantic)
       ↕
Display: Can show either or both
       ↕
Hash: ALWAYS computed from numeric

Structured Code:  E.Auth.Token.001
       ↓
Normalize:        E.AUTH.TOKEN.001 (uppercase)
       ↓
Hash (xxHash64):  [64-bit integer]
       ↓
Encode (Base62):  Xy8Qz

How the Parts Work Together#

Hierarchical Organization

Severity
  └─ Component (e.g., Auth)
      ├─ Primary (e.g., Token)
      │   ├─ Sequence 001 (TOKEN_MISSING)
      │   ├─ Sequence 002 (TOKEN_EXPIRED)
      │   └─ Sequence 003 (TOKEN_INVALID)
      │
      ├─ Primary (e.g., Session)
      │   ├─ Sequence 001 (SESSION_MISSING)
      │   └─ Sequence 013 (SESSION_CLOSED)
      │
      └─ Primary (e.g., Permission)
          └─ Sequence 008 (PERMISSION_DENIED)

Error Space

Each Component.Primary combination has 999 possible sequences (001-999).

E.Auth.Token.*           - 999 possible token-related errors
E.Auth.Session.*         - 999 possible session-related errors
E.Database.Connection.*  - 999 possible connection-related errors

Total space: (Components × Primaries × 999) = effectively unlimited

Dual Representation: Structured vs Compact#

WDP provides two ways to represent the same error:

Structured Code (Parts 1-4)

Format: SEVERITY.COMPONENT.PRIMARY.SEQUENCE

Example: E.Auth.Token.001

Use when:

• Writing logs (human-readable)
• Debugging (semantic meaning clear)
• Monitoring dashboards (can filter/group)
• Code comments (self-documenting)
• Developer communication

Benefits:

• Self-documenting
• Semantic meaning obvious
• Can grep/filter by component
• Understandable without lookup

Compact ID (Part 5)

Format: [0-9A-Za-z]{5}

Example: Xy8Qz

Use when:

• API responses (compact)
• Database storage (efficient)
• Network transmission (bandwidth-limited)
• User-facing references (easy to communicate)
• Mobile/IoT (constrained devices)

Benefits:

• Compact (5 chars vs ~15-30 chars)
• Easy to communicate (users can say "error Xy8Qz")
• Efficient storage
• URL-safe

Using Both Together

Logs:

[2024-01-15 10:30:00] ERROR E.Auth.Token.001 [Xy8Qz]: Token missing
                            ^^^^^^^^^^^^^^^^  ^^^^^
                            Semantic meaning  Searchable hash

API Response:

{
  "error": {
    "code": "E.Auth.Token.001",
    "compact_id": "Xy8Qz",
    "message": "Token missing from Authorization header",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Monitoring Dashboard:

Filter by component: E.Auth.*
Group by primary: E.Auth.Token.*, E.Auth.Session.*
Search by hash: Xy8Qz

User Support:

User: "I got error Xy8Qz"
Support: [looks up Xy8Qz] → E.Auth.Token.001 (TOKEN_MISSING)
         "You need to provide an authentication token"

Usage Patterns#

Pattern 1: Simple Logging

[ERROR] E.Auth.Token.001: Authentication failed

Use structured code only. Human-readable, self-documenting.

Pattern 2: Compact API

{"error": "Xy8Qz"}

Use compact ID only. Client looks up details in catalog.

Pattern 3: Full Context

[ERROR] E.Auth.Token.001 (Xy8Qz): Authentication failed

Use both. Semantic meaning + searchable hash.

Pattern 4: Structured Logging

{
  "severity": "error",
  "code": "E.Auth.Token.001",
  "compact_id": "Xy8Qz",
  "component": "Auth",
  "primary": "Token",
  "sequence": 1,
  "message": "Token missing"
}

Full decomposition for structured logging systems.

Benefits of the 5-Part Design#

1. Dual Representation

Humans:   E.Auth.Token.001 (readable, semantic)
Machines: Xy8Qz (compact, efficient)

Best of both worlds!

2. Hierarchical Organization

Group by component:  E.Auth.*
Filter by primary:   E.Auth.Token.*
Search by sequence:  *.*.*.001 (all "missing" errors)
Find specific:       Xy8Qz

3. Cross-Language Compatibility

Rust:       E.Auth.Token.001 -> Xy8Qz
Python:     E.Auth.Token.001 -> Xy8Qz
TypeScript: E.Auth.Token.001 -> Xy8Qz

Same code, same hash, everywhere

4. Graceful Degradation

If catalog unavailable:
- Structured code: Still somewhat understandable
  "E.Auth.Token.001" → probably auth token error
  
- Compact ID only: Meaningless without lookup
  "Xy8Qz" → what does this mean?

Redundancy provides fallback!

5. Flexible Adoption

Simple systems:     Use structured code only
Advanced systems:   Use full 5-part structure
Network-limited:    Use compact ID + catalog
Legacy integration: Map to/from other systems

One protocol, multiple adoption paths

Internationalization (i18n)#

Canonical Form

All error codes have a canonical English form:

[E.Auth.Token.001] -> Xy8Qz

Localized Aliases

Display can be localized, but hash is universal:

English:  [E.Auth.Token.001] -> Xy8Qz
Arabic:   [خ.المصادقة.الرمز.001] -> Xy8Qz
Japanese: [E.認証.トークン.001] -> Xy8Qz
Chinese:  [E.认证.令牌.001] -> Xy8Qz

Hash input:  E.AUTH.TOKEN.001 (canonical English, uppercase)
Hash output: Xy8Qz (same for all languages)

Users see localized display
Systems use universal hash

See: 8-I18N for complete internationalization specification

Common Questions#

Q: Do I need to use all 5 parts?

A: You can use structured code only OR compact ID only, depending on your needs. Both represent the same error.

Q: Can I add custom fields?

A: The 5-part structure is the protocol core. You can add custom metadata in your implementation, but the 5 parts ensure interoperability.

Q: What if I need more than 999 sequences?

A: This usually indicates your Component.Primary is too broad. Split it into more specific categories. Example: Parser.Syntax.*, Parser.Semantic.*, Parser.Lexical.*

Q: Are named sequences required?

A: No! Numeric sequences (001-999) are the canonical identity. Named sequences are optional aliases for documentation and code readability.

Q: Can components be logical, not just physical?

A: Yes! Components can be physical (Database), logical (Auth), services (UserService), or architectural layers (Api). Choose what fits your system.

Stability and Evolution#

For version 0.1.0-draft, the specification parts are classified by stability level:

Stable (Breaking changes unlikely)

These parts define the core protocol and are considered stable:

Provisional (May evolve with feedback)

These parts are well-designed but may evolve based on implementation experience:

Informative (Non-normative guidance)

These parts provide recommendations and may change freely:

Evolution Principles

1. Backward Compatibility: Stable parts will not introduce breaking changes without a major version bump
2. Catalog Versioning: The version field in catalogs enables graceful migration
3. Optional Extension: New features will be added as optional fields where possible
4. Deprecation Policy: Features will be deprecated before removal, with at least one minor version warning

Specification Documents#

For detailed implementation specifications, see:

Core Specification (Parts 1-5)

• 1-SEVERITY — Part 1: Severity levels
• 2-COMPONENT — Part 2: Component field
• 3-PRIMARY — Part 3: Primary field
• 4-SEQUENCE — Part 4: Sequence field
• 5-COMPACT-IDS — Part 5: Hash generation

Extensions & Conventions

• 6-SEQUENCE-CONVENTIONS — Informative: Recommended sequence meanings
• 7-NAMESPACES — Optional: Namespace collision prevention
• 8-I18N — Optional: Internationalization
• 9-CATALOGS — Optional: Catalog formats and usage
• 10-PRESENTATION — Informative: Visual guidelines
• 11-SECURITY — Security considerations
• 12-METADATA — Additional metadata

Quick Reference#

┌────────────────────────────────────────────────────────────────┐
│  WDP Error Code Structure                                      │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  [SEVERITY.COMPONENT.PRIMARY.SEQUENCE] -> COMPACT_ID           │
│   │        │         │        │            │                   │
│   │        │         │        │            └─ Part 5: Hash     │
│   │        │         │        └────────────── Part 4: Event    │
│   │        │         └─────────────────────── Part 3: Domain   │
│   │        └───────────────────────────────── Part 2: Module   │
│   └────────────────────────────────────────── Part 1: Urgency  │
│                                                                │
│  Example: [E.Auth.Token.001] -> Xy8Qz                          │
│                                                                │
│  Parts 1-4: Human-readable structured code                     │
│  Part 5:    Machine-friendly compact identifier                │
│                                                                │
│  Hash is ALWAYS generated from structured code                 │
│  Both representations can be used independently                │
└────────────────────────────────────────────────────────────────┘