Waddling Diagnostic Protocol (WDP) Specification

Overview#

E.Auth.Token.001 → sR5Kg
│ │    │     │       │
│ │    │     │       └─ Compact ID: 5-character fingerprint
│ │    │     └──────── Sequence: specific error instance
│ │    └────────────── Primary: failure domain (Token)
│ └─────────────────── Component: module (Auth)
└───────────────────── Severity: E = Error

Quickstart#

Minimal Implementation (Level 0)

Use WDP structured codes directly—no infrastructure required:

# Define errors in module namespaces (generic names compose well)
class token:  # auth_token module
    MISSING = "E.Auth.Token.001"   # 001 = MISSING
    EXPIRED = "E.Auth.Token.018"   # 018 = EXPIRED

class session:  # auth_session module
    TIMEOUT = "W.Auth.Session.017"  # 017 = TIMEOUT

# Use them
raise AuthError(token.EXPIRED, "Token expired at {timestamp}")

{"error": {"code": "E.Auth.Token.018", "message": "Token expired"}}

This is valid WDP. You get structured, queryable error codes immediately.

Add Compact IDs (Level 1)

Generate compact IDs for wire efficiency:

from wdp import compact_id

code = "E.Auth.Token.001"
cid = compact_id(code)  # → "sR5Kg"

{"error": {"code": "sR5Kg", "message": "Token expired"}}

See 5-COMPACT-IDS for the hash algorithm (xxHash3 + Base62).

Add Namespaces (Level 2)

When multiple services or libraries define codes independently:

from wdp import namespaced_compact_id

code = "E.Auth.Token.001"
cid = namespaced_compact_id("auth_service", code)  # → "05o5h-sR5Kg"

See 7-NAMESPACES for namespace hashing.

Add Catalogs (Level 3)

For i18n, message templates, and rich metadata:

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

Client expands using cached catalog → localized message with interpolated fields.

See 9-CATALOGS for the catalog system.

Specification Documents#

Core (Start Here)

Extended (As Needed)

Reference (Informative)

Key Concepts#

Catalog System (Optional)

Catalogs enable compact wire transmission with rich client-side expansion. A catalog is a JSON lookup table mapping compact IDs to full diagnostic metadata.

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

Note: Derivation is one-way. Structured code → compact ID is deterministic (hash). Compact ID → structured code requires a catalog lookup.

Namespaces (Optional)

Namespaces identify the origin of a diagnostic—which service, library, or team defined it.

Why namespaces matter: Two services might independently define E.Auth.Token.001. Without namespaces, these are indistinguishable:

Same code, different sources, unambiguous identification.

Use Cases#

1. IoT Devices

Problem: Constrained bandwidth and battery

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

Sensor → {"sR5Kg": {"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 with cached catalog
4. Supports multiple languages

3. Microservices Architecture

Problem: High-volume logging across distributed services

Solution: Compact log entries with efficient aggregation

Service A: [sR5Kg] Auth failure
Service B: [sR5Kg] Auth failure
Service C: [sR5Kg] 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 → {"sR5Kg": {"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"

Conformance Levels#

WDP defines four conformance levels:

Informative guidance (Parts 6, 10) applies at any level.

Most applications start at Level 0 or 1 and adopt higher levels as needed.

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:

Evolution Principles:

• Backward compatibility is prioritized for stable parts
• New features added as optional fields where possible
• Catalog version field enables graceful format evolution
• Deprecation before removal (minimum one minor version warning)

See STRUCTURE.md for detailed stability classifications.

Contributing#

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Ways to Contribute

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

License

This specification is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Copyright © 2025 Ashutosh Mahala

Author

Ashutosh Mahala (Ash)
GitLab: @AshutoshMahala
Repository: gitlab.com/AshutoshMahala/wdp-specs