Specification Structure Overview

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.

Protocol Overview#

The Waddling Diagnostic Protocol (WDP) is a structured, cross-language diagnostic coding system that provides both semantic structured codes and compact reference identifiers.

Problem Statement

Diagnostic systems face competing requirements for semantic richness and transmission efficiency:

• Fully descriptive diagnostic messages provide operational context but impose overhead for storage and transmission.
• Opaque numeric or short-form codes achieve efficiency but require external documentation for interpretation.

Protocol Approach

WDP addresses these requirements through dual representation. The same diagnostic MAY be expressed in two forms with deterministic bidirectional mapping:

Structured Code (E.Auth.Token.001): A hierarchical, dot-delimited format that encodes semantic information. The format is parsable by automated systems and readable by human operators. Systems MAY route, filter, and aggregate diagnostics based on the hierarchical structure.

Compact ID (V6a0B): A fixed-length, Base62-encoded hash derived from the structured code. The format is optimized for transmission efficiency, storage keys, and cross-system reference. The Compact ID is opaque; interpretation requires catalog lookup.

The 5-Part Structure#

Every WDP diagnostic code MUST consist 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
(Semantic, hierarchical,      |    (Efficient reference,
 parsable, actionable)        |     opaque handle, lookup key)

Complete Example

E.Auth.Token.001 -> V6a0B
^   ^    ^    ^       ^                                     
Part 4Part 5: Compact ID (5-char hash)

Both representations identify the same error:

• Structured code: E.Auth.Token.001 — semantic identity (parsable, routable, filterable)
• Compact ID: V6a0B — efficient reference (wire-friendly, lookup key, fingerprint)

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, 018, 003 (numeric)
       ↕
Associated Name: MISSING, EXPIRED (semantic)
       ↕
Display: MAY show either or both
       ↕
Hash: MUST be computed from numeric

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

How the Parts Work Together#

Hierarchical Organization

Severity
  └─ Component (e.g., Auth)
      ├─ Primary (e.g., Token)
      │   ├─ Sequence 001 (MISSING)
      │   ├─ Sequence 018 (EXPIRED)
      │   └─ Sequence 003 (INVALID)
      │
      ├─ Primary (e.g., Session)
      │   ├─ Sequence 001 (MISSING)
      │   └─ Sequence 013 (CLOSED)
      │
      └─ Primary (e.g., Permission)
          └─ Sequence 008 (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#

WDP defines two representations for the same diagnostic code. This section specifies the characteristics and appropriate usage of each representation.

Structured Code (Parts 1-4)

Format: SEVERITY.COMPONENT.PRIMARY.SEQUENCE

Example: E.Auth.Token.001

The structured code provides semantic identity through a hierarchical, dot-delimited format.

Characteristics

Recommended Usage

Implementations SHOULD use structured codes in the following contexts:

• Log output where searchability and readability are required
• Monitoring and observability systems requiring filtering by component or severity
• Routing and dispatch logic that acts on diagnostic hierarchy
• Documentation and code comments
• Debugging and troubleshooting workflows

Compact ID (Part 5)

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

Example: V6a0B

The Compact ID provides an efficient, fixed-length reference derived from the structured code through deterministic hashing.

Characteristics

Recommended Usage

Implementations SHOULD use Compact IDs in the following contexts:

• API responses where bandwidth efficiency is required
• Database primary keys and foreign key references
• Network transmission in constrained environments (IoT, mobile)
• User-facing error references for support workflows
• Cross-system correlation of diagnostics

Combined Usage

Implementations MAY transmit or store both representations simultaneously. This approach provides flexibility for systems with diverse consumption requirements.

Log Entry Example:

[2024-01-15 10:30:00] ERROR E.Auth.Token.001 [V6a0B]: Token missing

The structured code enables filtering and human interpretation; the Compact ID enables cross-system search.

API Response Example:

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

Monitoring System Example:

Filter by component: E.Auth.*
Group by primary: E.Auth.Token.*, E.Auth.Session.*
Search by Compact ID: V6a0B

User Support Workflow:

User reports: "error V6a0B"
Support lookup: V6a0B → E.Auth.Token.001 (MISSING)
Resolution: "Authentication token required"

Persistent Storage Considerations

When storing diagnostic codes in persistent storage systems, implementations SHOULD store both the decomposed structured code fields and the Compact ID. This approach enables both analytical queries on the hierarchical structure and efficient key-based lookups.

Schema Design

The following schema illustrates the RECOMMENDED approach for relational databases:

CREATE TABLE diagnostic_log (
    id            BIGINT PRIMARY KEY,
    compact_id    CHAR(5) NOT NULL,
    severity      CHAR(1) NOT NULL,
    component     VARCHAR(16) NOT NULL,
    primary_field VARCHAR(16) NOT NULL,
    sequence      SMALLINT NOT NULL,
    timestamp     TIMESTAMP NOT NULL
);

CREATE INDEX idx_compact_id ON diagnostic_log (compact_id);
CREATE INDEX idx_severity ON diagnostic_log (severity);
CREATE INDEX idx_component ON diagnostic_log (component);
CREATE INDEX idx_component_primary ON diagnostic_log (component, primary_field);

Query Patterns

Analytical queries utilize indexed structured fields:

-- Retrieve all critical diagnostics
SELECT * FROM diagnostic_log WHERE severity = 'C';

-- Retrieve diagnostics by component
SELECT * FROM diagnostic_log WHERE component = 'Auth';

-- Retrieve diagnostics by component and primary
SELECT * FROM diagnostic_log 
  WHERE component = 'Auth' AND primary_field = 'Token';

-- Aggregate by component
SELECT component, COUNT(*) FROM diagnostic_log GROUP BY component;

Reference lookups utilize the Compact ID:

-- Direct lookup by Compact ID
SELECT * FROM diagnostic_log WHERE compact_id = 'V6a0B';

-- Join using Compact ID as foreign key
SELECT d.*, u.email FROM diagnostic_log d
  JOIN users u ON u.last_error_id = d.compact_id;

Rationale

The decomposed structured fields enable efficient analytical queries through database indexing. Query planners MAY utilize indexes on severity, component, or primary fields to optimize filtering, grouping, and aggregation operations.

The Compact ID provides a fixed-length, collision-resistant key suitable for primary key usage, foreign key references, and cross-table joins.

Usage Patterns#

The following patterns demonstrate RECOMMENDED approaches for different use cases.

Pattern 1: Simple Logging

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

Structured code only. Human-readable and self-documenting.

Pattern 2: Compact API

{"error": "V6a0B"}

Compact ID only. Client resolves details via catalog lookup.

Pattern 3: Full Context

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

Both representations. Provides semantic meaning and searchable hash.

Pattern 4: Structured Logging

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

Full decomposition for structured logging systems. RECOMMENDED for observability platforms.

Design Rationale#

This section provides informative discussion of the architectural benefits achieved through the WDP design.

Dual Representation Benefits

The dual representation model addresses distinct requirements through complementary formats:

Structured codes provide semantic topology that enables programmatic routing, filtering, and aggregation. The hierarchical format is interpretable by both human operators and automated systems.

Compact IDs provide efficient, opaque references suitable for storage keys, foreign key relationships, and bandwidth-constrained transmission. The deterministic derivation ensures bidirectional mapping between representations.

Hierarchical Organization Benefits

The structured code format enables hierarchical operations through pattern matching:

This hierarchical structure benefits both human operators (through readability) and automated systems (through programmatic decomposition).

Cross-Language Compatibility

The same structured code MUST produce the same compact ID across all conforming implementations:

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

This property is REQUIRED by the deterministic hash algorithm specified in 5-COMPACT-IDS.

Graceful Degradation

Structured codes provide partial interpretability when catalog lookup is unavailable:

This property provides operational resilience in degraded conditions. Implementations SHOULD prefer structured codes in contexts where catalog availability cannot be guaranteed.

Flexible Adoption

WDP supports multiple adoption strategies:

Implementations MAY adopt any strategy appropriate to their requirements.

Internationalization (i18n)#

Canonical Form

All diagnostic codes have a canonical English form that MUST be used for hash computation:

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

Localized Aliases

Display MAY be localized, but the hash MUST remain universal:

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

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

Users see localized display
Systems use universal hash

See: 8-I18N for complete internationalization specification

Frequently Asked Questions#

This section provides clarification on common questions. These answers are INFORMATIVE.

10.1 Representation Requirements

Do implementations need to use all 5 parts?

No. Implementations MAY use structured code only OR compact ID only, depending on requirements. Both representations identify the same diagnostic. The choice depends on the use case (see Usage Patterns above).

10.2 Custom Fields

Can implementations add custom fields beyond the 5 parts?

Yes. The 5-part structure defines the protocol core for interoperability. Implementations MAY add custom metadata fields. See 12-METADATA for the metadata extension specification.

10.3 Sequence Capacity

What if a Component.Primary requires more than 999 sequences?

This typically indicates the Component.Primary scope is too broad. The RECOMMENDED approach is to split into more specific categories. For example, Parser.Syntax.*, Parser.Semantic.*, and Parser.Lexical.* instead of a single Parser.Error.*.

10.4 Named Sequences

Are named sequences required?

No. Numeric sequences (001-999) constitute the canonical identity and MUST be used for hash computation. However, every sequence number MUST have a documented semantic meaning in at least one authoritative source (catalog entry, specification document, or source code definition).

Named aliases (such as EXPIRED or MISSING) are OPTIONAL. Implementations MAY define named constants in code, or MAY document sequence meanings exclusively in catalog entries without corresponding code constants.

Composition Guidance: Sequence names SHOULD be sufficiently generic to compose semantically with multiple Primary values. For example, the sequence name EXPIRED (rather than TOKEN_EXPIRED) enables meaningful composition across Primary domains: Token.EXPIRED, Session.EXPIRED, Certificate.EXPIRED. The Primary field identifies the subject; the Sequence field identifies the condition or state.

See 6-SEQUENCE-CONVENTIONS for naming conventions.

10.5 Component Types

Can components represent logical modules, not just physical subsystems?

Yes. Components MAY represent:

• Physical subsystems (Database, Network)
• Logical modules (Auth, Validation)
• Service boundaries (UserService, PaymentGateway)
• Architectural layers (Api, Domain)

See 2-COMPONENT for complete guidance.

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 SHALL NOT introduce breaking changes without a major version increment
2. Catalog Versioning: The version field in catalogs enables graceful migration
3. Optional Extension: New features SHALL be added as optional fields where possible
4. Deprecation Policy: Features SHALL be deprecated before removal, with at least one minor version warning

Specification Documents#

For detailed implementation specifications, see the following normative and informative documents.

12.1 Core Specification (Parts 1-5)

These documents define the REQUIRED elements of WDP.

12.2 Extended Specification (Parts 6-12)

These documents define OPTIONAL extensions and implementation guidance.

12.3 Supporting Documents

Appendix A. Quick Reference#

E.Auth.Token.001 -> V6a0B
^   ^    ^    ^       ^                                     
PaPart Part 4: EPart 5: Hash

Appendix B. Normative References#

• [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
• [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017.