Core Part3 of 5

Version0.1.0-draft

Last Updated2025-11-30

StatusDraft

TypeNORMATIVE (Core)

WDP Part 3: Primary Field Specification

Specification of the Primary Field (Part 3) of the Waddling Diagnostic Protocol (WDP) error code structure. The primary field identifies the specific failure domain or category within a component.

Abstract#

This document specifies the Primary Field (Part 3) of the Waddling Diagnostic Protocol (WDP) error code structure. The primary field identifies the specific failure domain or category within a component, providing finer-grained classification of diagnostic events.

Specification Navigation: See STRUCTURE.md for an overview of all WDP specification parts.

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.

1. Introduction#

The primary field is the third part of the five-part WDP error code structure:

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

The primary field refines the component by identifying a specific subsystem, operation type, or failure domain.

2. Purpose#

The primary field serves to:

Subdivide components into logical failure domains
Classify error types within a component boundary
Enable filtering and routing based on category
Improve diagnostics by narrowing the scope of investigation
Organize error catalogs hierarchically

Example Hierarchy

Component: Auth
  ├─ Primary: Token      (token-related auth issues)
  ├─ Primary: Session    (session-related auth issues)
  └─ Primary: Permission (permission-related auth issues)

Component: Database
  ├─ Primary: Connection (connection issues)
  ├─ Primary: Query      (query execution issues)
  └─ Primary: Migration  (migration issues)

3. Format Specification#

3.1 Naming Convention

Display Form: PascalCase (UpperCamelCase)
Hash Canonical Form: UPPERCASE (normalized before hashing)

3.2 Field Properties

Property	Value
Pattern	Starts with uppercase letter, followed by letters and/or digits
Maximum Length	16 characters
Recommended Length	8–12 characters
Character Set	ASCII letters (a-z, A-Z) and digits (0-9) only
Position	Third field in the error code
Required	YES

3.3 Regular Expression

^[A-Z][a-zA-Z0-9]{0,15}$

Explanation:

^ - Start of string
[A-Z] - Must start with uppercase letter
[a-zA-Z0-9]{0,15} - Followed by 0-15 letters or digits
$ - End of string

3.4 Hash Normalization

Before computing the compact ID hash, the primary field MUST be normalized to UPPERCASE:

Display Form:

E.Auth.Token.001 -> 3xK9m

Hash Input (Canonical Form):

E.AUTH.TOKEN.001  (normalized to uppercase before hashing)

This ensures case-insensitive, deterministic compact ID generation.

4. Relationship to Component#

The primary field refines and subdivides the component. Together, Component.Primary forms a hierarchical namespace:

4.1 Auth Component Examples

Component.Primary	Meaning
Auth.Token	Token-related auth issues
Auth.Session	Session-related auth issues
Auth.Permission	Permission-related auth issues
Auth.Credential	Credential validation issues
Auth.Provider	External auth provider issues

4.2 Database Component Examples

Component.Primary	Meaning
Database.Connection	Database connection issues
Database.Query	Database query issues
Database.Migration	Database migration issues
Database.Transaction	Transaction management issues
Database.Schema	Schema validation issues

4.3 Parser Component Examples

Component.Primary	Meaning
Parser.Syntax	Syntax parsing errors
Parser.Validation	Validation errors
Parser.Lexer	Lexical analysis errors
Parser.Semantic	Semantic analysis errors

5. Common Primary Categories#

Below are frequently used primary field values organized by domain:

5.1 Authentication & Authorization

Token              - Token operations (JWT, API keys, refresh tokens)
Session            - Session management and lifecycle
Permission         - Permission and authorization checks
Credential         - Username/password validation
Provider           - External identity provider integration

5.2 Data & Storage

Connection         - Connection management
Query              - Query operations
Transaction        - Transaction handling
Schema             - Schema validation
Migration          - Data migration
Validation         - Data validation

5.3 Network & Communication

Request            - Request processing
Response           - Response generation
Connection         - Network connection
Timeout            - Timeout conditions
Protocol           - Protocol handling

5.4 Processing & Parsing

Syntax             - Syntax checking
Validation         - Input validation
Lexer              - Lexical analysis
Parser             - Parsing operations
Semantic           - Semantic analysis
Transform          - Data transformation

5.5 System & Infrastructure

Configuration      - Configuration issues
State              - State management
Resource           - Resource allocation
Initialization     - Initialization
Shutdown           - Cleanup and shutdown

6. Naming Guidelines#

6.1 Best Practices

DO:

✅ Use descriptive, domain-specific names
✅ Keep names concise (8–12 characters recommended)
✅ Use singular nouns (e.g., Token, not Tokens)
✅ Use PascalCase consistently
✅ Choose names that clearly indicate the failure domain

DON'T:

❌ Use abbreviations unless widely understood (e.g., JWT is acceptable, Tok is not)
❌ Include component name in primary (e.g., AuthToken when component is Auth)
❌ Use underscores, hyphens, or special characters
❌ Start with lowercase letters
❌ Exceed 16 characters

6.2 Naming Patterns

Operation-Based:

Validation
Connection
Processing
Execution

Resource-Based:

Token
Session
Query
Schema

Phase-Based:

Initialization
Runtime
Shutdown
Migration

7. Validation Rules#

7.1 Format Validation

Implementations MUST validate that the primary field:

Starts with an uppercase ASCII letter (A-Z)
Contains only ASCII letters (a-z, A-Z) and digits (0-9)
Does not exceed 16 characters
Does not contain whitespace, underscores, hyphens, or special characters

7.2 Validation Regex

^[A-Z][a-zA-Z0-9]{0,15}$

7.3 Validation Examples

Valid Primary Fields:

Token           ✅ (common)
Connection      ✅ (common)
Query           ✅ (common)
Permission      ✅ (10 chars)
Validation      ✅ (10 chars)
Initialization  ✅ (14 chars - within limit)
Config          ✅ (acceptable abbreviation)
JWT             ✅ (well-known acronym)
OAuth2          ✅ (includes digit)

Invalid Primary Fields:

token           ❌ Must start with uppercase
TOKEN           ❌ Should use PascalCase (display form)
connection_pool ❌ No underscores allowed
query-builder   ❌ No hyphens allowed
Init            ❌ Ambiguous abbreviation (use Initialization)
VeryLongPrimaryFieldName ❌ Exceeds 16 characters (24 chars)

8. Examples#

8.1 Complete Error Codes

E.Auth.Token.001 -> 3xK9m
  Component: Auth
  Primary:   Token
  Meaning:   Authentication token error, sequence 001

W.Database.Connection.017 -> 7aB2c
  Component: Database
  Primary:   Connection
  Meaning:   Database connection warning, sequence 017 (TIMEOUT)

E.Parser.Syntax.003 -> 9zX1q
  Component: Parser
  Primary:   Syntax
  Meaning:   Syntax parsing error, sequence 003 (INVALID)

8.2 Hierarchical Organization

Auth Component:
  E.Auth.Token.001       -> Token missing          (001 = MISSING)
  E.Auth.Token.018       -> Token expired          (018 = STALE)
  E.Auth.Token.003       -> Token invalid          (003 = INVALID)
  
  E.Auth.Session.021     -> Session not found      (021 = NOTFOUND)
  E.Auth.Session.018     -> Session expired        (018 = STALE)
  
  E.Auth.Permission.008  -> Insufficient privileges (008 = DENIED)
  E.Auth.Permission.008  -> Resource forbidden     (008 = DENIED)

Database Component:
  E.Database.Connection.008 -> Connection refused  (008 = DENIED)
  E.Database.Connection.017 -> Connection timeout  (017 = TIMEOUT)
  
  E.Database.Query.003      -> Query syntax error  (003 = INVALID)
  E.Database.Query.017      -> Query timeout       (017 = TIMEOUT)
  
  E.Database.Schema.002     -> Schema mismatch     (002 = MISMATCH)
  E.Database.Migration.027  -> Migration failed    (027 = UNAVAILABLE)

8.3 Cross-Component Patterns

Notice how the same primary field can appear across different components:

Auth.Connection      - Authentication provider connection
Database.Connection  - Database connection
Network.Connection   - Network socket connection
Cache.Connection     - Cache server connection

Each Connection primary has different semantics depending on its component.

Normative References#

STRUCTURE.md - WDP error code structure overview
2-COMPONENT.md - Component field specification
4-SEQUENCE.md - Sequence field specification
5-COMPACT-IDS.md - Compact ID generation

Conformance#

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.