Getting Started with WDP

Abstract#

The Waddling Diagnostic Protocol (WDP) is a comprehensive, structured error coding system designed for modern distributed systems. It provides:

• Structured, semantic error codes for human readability and debugging
• Compact IDs for efficient network transmission and storage
• Multi-language support through catalog-based expansion
• Namespace isolation for multi-service architectures
• Offline capability through client-side catalog caching
• Efficient wire format with minimal transmission overhead

WDP solves the challenge of creating error codes that are both meaningful to developers and efficient for systems.

Quick Example#

Traditional approach:

{
  "error": {
    "code": "E.AUTH.TOKEN.EXPIRED",
    "message": "Token expired at 2024-01-15T10:30:00Z",
    "description": "The JWT token has exceeded its TTL."
  }
}

WDP approach:

{
  "xY9Kp": {
    "f": {"timestamp": "2024-01-15T10:30:00Z"}
  }
}

Client expands xY9Kp using a pre-downloaded catalog to display:

❌ Error: Token expired at 2024-01-15T10:30:00Z
💡 Use /auth/refresh endpoint with refresh token

Recommended Reading Order#

1. Start Here

• Overview (STRUCTURE) — Overview of the 5-part error code structure

2. Core Specifications (Parts 1-5)

• 1-SEVERITY — Severity levels (E, W, C, I, H, etc.)
• 2-COMPONENT — System module identification
• 3-PRIMARY — Failure domain within component
• 4-SEQUENCE — Specific error instance numbering
• 5-COMPACT-IDS — Hash-based compact identifiers

3. Conventions

• 6-SEQUENCE-CONVENTIONS — Sequence numbering best practices

4. Multi-Service Support

• 7-NAMESPACES — Namespace collision prevention

5. Internationalization

• 8-I18N — Multi-language support

6. Catalog System (Part 9)

• 9-CATALOGS — Overview of catalog system
• 9a-CATALOG-FORMAT — JSON catalog file format
• 9b-WIRE-PROTOCOL — HTTP wire protocol
• 9c-IMPLEMENTATION — Practical implementation guide

7. User Experience

• 10-PRESENTATION — UI/UX guidelines for displaying diagnostics

8. Security & Metadata

• 11-SECURITY — Security considerations and PII handling
• 12-METADATA — Additional diagnostic metadata

Architecture#

The 5-Part Structure

Every WDP error code consists of five parts:

E.Auth.Token.001 → xY9Kp
│ │    │     │     │
│ │    │     │     └─ Part 5: Compact ID (5-char hash)
│ │    │     └──────── Part 4: Sequence (001)
│ │    └────────────── Part 3: Primary (Token)
│ └─────────────────── Part 2: Component (Auth)
└───────────────────── Part 1: Severity (E = Error)

Dual representation:

• Parts 1-4: Human-readable structured code (E.AUTH.TOKEN.001)
• Part 5: Machine-friendly compact ID (xY9Kp)

Both identify the same diagnostic but serve different purposes.

Catalog-Based Expansion

WDP uses a catalog system to enable efficient transmission:

┌─────────────────┐
│  Server         │  Sends: {"xY9Kp": {"f": {"timestamp": "..."}}}
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Client         │  1. Downloads catalog once (cached)
│  + Catalog      │  2. Looks up xY9Kp → full metadata
│                 │  3. Interpolates fields
│                 │  4. Displays: "Token expired at ..."
└─────────────────┘

Benefits:

• Compact wire format with efficient transmission
• Offline expansion capability
• Multi-language support (different catalogs per language)
• Consistent error identification across services

Namespace Support

For multi-service architectures, WDP supports namespaces to prevent collision:

Single-namespace catalog (90% of use cases):

{
  "namespace": "auth_service",
  "diags": {
    "xY9Kp": {"code": "E.Auth.Token.001", ...}
  }
}

Aggregated catalog (monitoring, gateways):

{
  "namespaces": {
    "auth_service": "h4tYw2",
    "payment_service": "k9Px3a"
  },
  "diags": {
    "h4tYw2-xY9Kp": {"code": "E.Auth.Token.001", ...},
    "k9Px3a-mN3Yr": {"code": "E.Payment.Invalid.001", ...}
  }
}

See 7-NAMESPACES for details.

Use Cases#

1. IoT Devices

Problem: Constrained bandwidth and battery

Solution: Send 5-character compact IDs instead of full error messages

Sensor → {"xY9Kp": {"f": {"temp": "45.2"}}}
Gateway expands → "Temperature 45.2°C exceeds threshold"

2. Mobile Applications

Problem: Slow/expensive mobile networks

Solution: Download catalog once, expand errors locally

1. App downloads catalog (cached for 7 days)
2. API returns compact diagnostics
3. App expands locally (works offline)
4. Supports multiple languages

3. Microservices Architecture

Problem: High-volume logging across distributed services

Solution: Compact log entries with efficient aggregation

Service A: [xY9Kp] Auth failure
Service B: [xY9Kp] Auth failure
Service C: [xY9Kp] Auth failure
→ Centralized logging aggregates by compact ID

4. Multi-Language Support

Problem: Supporting multiple languages efficiently

Solution: Same compact IDs, different language catalogs

Backend → {"xY9Kp": {"f": {"timestamp": "2024-01-15"}}}

English client:  "Token expired at 2024-01-15"
Spanish client:  "Token expiró el 2024-01-15"
Japanese client: "トークンの有効期限が切れました 2024-01-15"

Key Features#

Conformance Levels#

WDP defines three conformance levels:

Status#

This specification is currently in DRAFT status. All documents are subject to change based on implementation feedback and community discussion.

Specification Stability

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

Contributing#

We welcome contributions! Please see the contributing guidelines for details.

Ways to Contribute

• Report issues or suggest improvements
• Propose new features or extensions
• Share implementation feedback
• Improve documentation and examples

Quick Links

• GitLab Repository: gitlab.com/AshutoshMahala/wdp-specs
• Issues: gitlab.com/AshutoshMahala/wdp-specs/-/issues