RDCP Primitive Types

RDCP Protocol Primitive Types

This page defines RDCP primitive types built on JSON’s base types. These primitives add semantic constraints and validation rules that ensure interoperability across implementations.

The definitions here are normative for RDCP v1.0 and align with the validation enforced by the core schemas in @rdcp.dev/core.

Type Hierarchy

RDCP Protocol Data Types
========================

JSON Base Types (RFC 8259)
├── string
│   ├── Timestamp
│   │   Format: YYYY-MM-DDTHH:mm:ss.sssZ (UTC; milliseconds required)
│   │   Example: "2025-09-17T10:30:00.000Z"
│   │   Validation: Must end with 'Z'; no timezone offsets
│   │
│   ├── Duration
│   │   Accepts: integer seconds OR string pattern
│   │   String format: <number>(s|m|h|d)
│   │   Examples: 900, "15m", "2h", "30s"
│   │   Canonicalization (SHOULD): emit smallest evenly divisible unit
│   │
│   ├── CategoryName
│   │   Pattern: ^[A-Z][A-Z0-9_]{0,63}$
│   │   Length: 1–64 characters
│   │   Case: UPPERCASE_WITH_UNDERSCORES
│   │   Examples: DATABASE, API_ROUTES, QUERY_CACHE
│   │
│   ├── Identifier
│   │   Pattern: ^[a-zA-Z0-9._-]{1,255}$
│   │   Length: 1–255 characters
│   │   Usage: TenantId, ClientId, RequestId (general purpose)
│   │   Examples: tenant-123, client.app, req_abc123
│   │
│   └── ErrorCode
│       Pattern: ^[A-Z0-9_]{3,64}$
│       Length: 3–64 characters
│       Examples: RDCP_AUTH_REQUIRED, RDCP_RATE_LIMITED
│
├── number (finite double-precision floating point)
│   ├── CounterNumber
│   │   Constraint: >= 0
│   │   Usage: Counts, totals, accumulations, sizes
│   │
│   ├── RateNumber
│   │   Constraint: >= 0
│   │   Usage: Per-second metrics, throughput
│   │
│   └── GaugeNumber
│       Constraint: Finite (no NaN/Infinity)
│       Usage: Values that may be negative (runtime/internal use)
│
├── boolean
│   Used as-is from JSON
│   Examples: enabled, temporary, authenticated
│
├── object {...}
│   Protocol structures (ControlRequest, DiscoveryResponse, etc.)
│   Built from primitive types
│
└── array [...]
    └── CategoryList
        Type: array of CategoryName
        Constraints:
          - unique items (no duplicates)
          - minimum 1 item
        Example: ["DATABASE", "API_ROUTES", "CACHE"]

Detailed Type Definitions

Timestamp

Type: string (ISO 8601 / RFC 3339 in UTC)

Format: YYYY-MM-DDTHH:mm:ss.sssZ

• Milliseconds are required (.sss)
• Must end with Z (UTC)
• Timezone offsets other than Z are not permitted

Examples:

• Valid: "2025-09-17T10:30:00.000Z"
• Valid: "2025-12-31T23:59:59.999Z"
• Invalid: "2025-09-17T10:30:00" (missing Z)
• Invalid: "2025-09-17T10:30:00+05:00" (offset not allowed)

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

Duration

Type: number | string

Number form: Integer seconds

• Examples: 900 (15 minutes), 3600 (1 hour)

String form: <number><unit> where unit ∈ {s, m, h, d}

• Pattern: ^[0-9]+(s|m|h|d)$
• Examples: "15m", "2h", "30s", "7d"

Canonicalization (recommendation):

• Implementations SHOULD prefer string form using the smallest evenly divisible unit when emitting durations.
  • 900 → "15m" (not "900s")
  • 7200 → "2h" (not "120m")
  • 61 → "61s" (cannot reduce further)

Note (Health endpoint): The health check field checks[].duration intentionally uses an implementation-specific millisecond string (e.g. "5ms"), and does not use the Duration primitive defined above.

CategoryName

Type: string

Pattern: ^[A-Z][A-Z0-9_]{0,63}$

• Must start with uppercase letter
• Subsequent characters: uppercase letters, digits, underscores
• Length: 1–64 characters
• Case: UPPERCASE_WITH_UNDERSCORES

Valid examples:

• DATABASE
• API_ROUTES
• QUERY_CACHE
• AUTH_2FA

Invalid examples:

• database (lowercase)
• Api-Routes (hyphen not allowed)
• _CACHE (cannot start with underscore)

Identifier

Type: string

Pattern: ^[a-zA-Z0-9._-]{1,255}$

• Alphanumeric plus period, underscore, hyphen
• No whitespace
• URL-safe characters only
• Length: 1–255 characters

Usage contexts:

• TenantId: Tenant identifier in multi-tenant systems
• ClientId: Client application identifier
• RequestId: General-purpose correlation identifier (note: some APIs prefer UUID v4 specifically)

Valid examples:

• tenant-123
• client.app.v2
• req_abc123_xyz
• org.example.service

Invalid examples:

• tenant 123 (whitespace)
• client@app (@ not allowed)
• Empty string

ErrorCode

Type: string

Pattern: ^[A-Z0-9_]{3,64}$

• Uppercase letters, digits, underscores only
• Length: 3–64 characters

Standard RDCP error codes (selected):

• Authentication/Authorization: RDCP_AUTH_REQUIRED, RDCP_INVALID_TOKEN, RDCP_TOKEN_EXPIRED, RDCP_FORBIDDEN, RDCP_INVALID_CLIENT
• Validation/Protocol: RDCP_VALIDATION_ERROR, RDCP_INVALID_ACTION, RDCP_INVALID_CATEGORY, RDCP_CATEGORY_NOT_FOUND, RDCP_MISSING_PARAMETER, RDCP_INVALID_PROTOCOL, RDCP_NOT_FOUND, RDCP_REQUEST_ID_INVALID, RDCP_UNSUPPORTED_VERSION, RDCP_MALFORMED_REQUEST
• Server/Availability: RDCP_SERVER_ERROR, RDCP_INTERNAL_ERROR, RDCP_UNAVAILABLE, RDCP_TIMEOUT, RDCP_CONFIGURATION_ERROR, RDCP_STORAGE_ERROR, RDCP_AUDIT_WRITE_FAILED, RDCP_RATE_LIMIT_MISCONFIGURED

See also: Protocol-Error-Codes (generated)

CategoryList

Type: array of CategoryName

Constraints:

• Must contain at least 1 item (minItems: 1)
• All items must be unique (uniqueItems: true)
• Each item must be a valid CategoryName

Valid examples:

["DATABASE"]
["DATABASE", "API_ROUTES", "CACHE"]

Invalid examples:

[]                       // Empty array not allowed
["DATABASE", "DATABASE"] // Duplicates not allowed
["database"]             // Invalid CategoryName format

MetricNumber Types

CounterNumber

Type: number

Constraint: >= 0 (non-negative)

Usage: Counters, totals, accumulations, sizes

Examples:

• requestCount: 1234
• activeSessions: 42
• bytesProcessed: 1048576
• errorCount: 0

Invalid: -5

RateNumber

Type: number

Constraint: >= 0 (non-negative)

Usage: Per-second metrics, throughput, rates

Examples:

• requestsPerSecond: 2.3
• callsPerSecond: 0.5
• throughput: 1000.0

Invalid: -1.5

GaugeNumber

Type: number

Constraint: Finite (no NaN or ±Infinity); in wire JSON, numbers are already finite.

Usage: Values that can legitimately be negative; reserved for specialized metrics. Prefer counters/rates when possible.

Examples:

• temperatureDelta: -5.2
• cacheDifference: 150.0
• memoryDelta: -1024

Central JSON Schema $defs (authoritative)

These are the centralized schema definitions used for validation (strict Timestamp with required milliseconds):

{
  "$id": "https://rdcp.dev/schemas/defs.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Timestamp": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
    },
    "Duration": {
      "oneOf": [
        { "type": "integer", "minimum": 0 },
        { "type": "string", "pattern": "^[0-9]+(s|m|h|d)$" }
      ]
    },
    "CategoryName": {
      "type": "string",
      "pattern": "^[A-Z][A-Z0-9_]{0,63}$",
      "maxLength": 64
    },
    "Identifier": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9._-]{1,255}$",
      "maxLength": 255
    },
    "ErrorCode": {
      "type": "string",
      "pattern": "^[A-Z0-9_]{3,64}$",
      "minLength": 3,
      "maxLength": 64
    },
    "CategoryList": {
      "type": "array",
      "items": { "$ref": "#/$defs/CategoryName" },
      "minItems": 1,
      "uniqueItems": true
    },
    "CounterNumber": {
      "type": "number",
      "minimum": 0
    },
    "RateNumber": {
      "type": "number",
      "minimum": 0
    },
    "GaugeNumber": {
      "type": "number"
    }
  }
}

Note: If the repository’s docs/schemas/defs.json still allows optional milliseconds for Timestamp, it should be updated to the strict pattern above to match the core validation and this page.

Conformance Checklist

• Timestamps include milliseconds and end with Z (UTC)
• CategoryList contains 1+ unique items; each item matches CategoryName pattern
• Duration is integer seconds or matches s|m|h|d pattern; servers SHOULD canonicalize on output
• Counters and rates are non-negative numbers
• ErrorCode values match RDCP standard codes and the ErrorCode pattern

Endpoint Differences

• HealthResponse checks[].duration uses an implementation-specific ms string (e.g., "5ms"); other uses of duration follow the Duration primitive.

References

• Protocol Specification (wiki): RDCP-Protocol-Specification
• Protocol Schemas (wiki): Protocol-Schemas
• Error Codes (generated; wiki): Protocol-Error-Codes
• Core Package: https://www.npmjs.com/package/@rdcp.dev/core
• RFC 3339 (Timestamps): https://www.rfc-editor.org/rfc/rfc3339
• RFC 8259 (JSON): https://www.rfc-editor.org/rfc/rfc8259
• JSON Schema: https://json-schema.org/

---

Version: RDCP Protocol v1.0
License: Apache 2.0
Last Updated: 2025-09-30