Alteriom MQTT v1 JSON Schemas, TypeScript types, and production‑ready validation helpers for integrating firmware MQTT payloads into web or backend services.

Firmware emits structured MQTT payloads that must remain tightly aligned with web, analytics, and gateway logic. This package is the single source of truth for:

• Canonical, versioned JSON Schemas (schema_version: 1 series)
• Embedded (tree‑shakeable) schema objects — no runtime file I/O
• Precompiled Ajv validators (fast + consistent across CJS / ESM)
• TypeScript interfaces & type guards generated from the same source schema set
• Message classification helper that infers the schema kind heuristically
• Forward‑compatible design: unknown extra properties are ignored unless explicitly constrained

• Dual build: CommonJS + ESM (Node 16+ / bundlers)
• Zero configuration: just import and validate
• Helpful error paths (JSON Pointer style)
• Lightweight (Ajv peer dependency, schemas embedded)
• Ships original schema JSON files (optional consumption)
• NEW in v0.8.0: ⚠️ BREAKING: Gateway code realignment (300→305, 301→306) with automatic legacy translation
• NEW in v0.8.0: Unified device schemas (10x range) for sensor/gateway/bridge/hybrid deployments
• NEW in v0.8.0: HTTP transport support via transport_metadata for REST API integration
• NEW in v0.8.0: Bridge management schemas for painlessMesh v1.8.0+ (5 new message types)
• NEW in v0.7.3: Message batching for 50-90% protocol overhead reduction
• NEW in v0.7.3: Compression support for 60-80% bandwidth savings (gzip, zlib, brotli, deflate)
• NEW in v0.7.3: Comprehensive example repository (9 examples, 4 categories)
• NEW in v0.7.3: Professional code quality tooling (ESLint, Prettier, Husky)
• NEW in v0.7.3: 87% test coverage with 134 tests (28 unit, 12 integration, 68 fixtures)
• NEW in v0.7.1: Message type codes for significantly faster classification and standardized routing
• NEW in v0.7.1: PainlessMesh bridge schema for mesh protocol integration
• NEW in v0.7.0: Best-in-class OTA management with security, rollback, and delta updates
• NEW in v0.6.0: Enhanced location/geolocation support for asset tracking
• NEW in v0.6.0: Extended sensor metadata (accuracy, calibration, operational range)
• NEW in v0.6.0: Comprehensive gateway health metrics (storage, network, errors)

📚 GitHub Wiki - Comprehensive API documentation, schema references, validation rules, and guides

Note: If the wiki appears empty, see WIKI_SETUP.md for setup instructions. The wiki is automatically generated and synced from the repository.

npm install @alteriom/mqtt-schema ajv ajv-formats

Support & Compatibility: Node 18+ tested; Node 20 primary. Dual CJS/ESM builds.

For optimal performance, include the optional message_type field:

import { classifyAndValidate, MessageTypeCodes } from '@alteriom/mqtt-schema';

const payload = {
  schema_version: 1,
  message_type: MessageTypeCodes.SENSOR_DATA, // 200 - enables 90% faster classification
  device_id: 'SN001',
  device_type: 'sensor',
  timestamp: new Date().toISOString(),
  firmware_version: 'SN 2.1.5',
  sensors: {
    temperature: { value: 22.5, unit: 'C' }
  }
};

const { kind, result } = classifyAndValidate(payload);
// Fast path: O(1) lookup vs O(n) heuristics

import { validators } from '@alteriom/mqtt-schema';

const payload = JSON.parse(rawMqttString);
const result = validators.sensorData(payload);
if (!result.valid) {
  console.error('Invalid sensor data', result.errors);
}

Classify and validate automatically:

import { classifyAndValidate } from '@alteriom/mqtt-schema';

const { kind, result } = classifyAndValidate(payload);
if (result.valid) {
  console.log('Message kind:', kind);
} else {
  console.warn('Validation errors', result.errors);
}

Use strong TypeScript types after classification:

import { classifyAndValidate, isSensorDataMessage, SensorDataMessage } from '@alteriom/mqtt-schema';

const { result } = classifyAndValidate(payload);
if (result.valid && isSensorDataMessage(payload)) {
  const data: SensorDataMessage = payload;
  Object.entries(data.sensors).forEach(([name, s]) => {
    console.log(name, s.value, s.unit);
  });
}

Access raw schema JSON (if you need to introspect or power form generation):

import envelopeSchema from '@alteriom/mqtt-schema/schemas/envelope.schema.json';

Send commands to devices and receive responses with correlation tracking:

import { validators, isCommandMessage, isCommandResponseMessage } from '@alteriom/mqtt-schema';

// Create a command message
const command = {
  schema_version: 1,
  device_id: 'ALT-441D64F804A0',
  device_type: 'sensor',
  timestamp: new Date().toISOString(),
  firmware_version: 'WEB 1.0.0',
  event: 'command',
  command: 'read_sensors',
  correlation_id: `cmd-${Date.now()}-001`,
  parameters: {
    immediate: true,
    sensors: ['temperature', 'humidity']
  },
  priority: 'high'
};

// Validate before sending
const cmdResult = validators.command(command);
if (cmdResult.valid) {
  // Publish to MQTT topic: alteriom/nodes/{device_id}/commands
  mqttClient.publish(`alteriom/nodes/${command.device_id}/commands`, JSON.stringify(command));
}

// Handle response from device
mqttClient.subscribe(`alteriom/nodes/${command.device_id}/responses`, (message) => {
  const response = JSON.parse(message);
  const respResult = validators.commandResponse(response);
  
  if (respResult.valid && isCommandResponseMessage(response)) {
    if (response.correlation_id === command.correlation_id) {
      if (response.success) {
        console.log('Command succeeded:', response.result);
        console.log(`Latency: ${response.latency_ms}ms`);
      } else {
        console.error(`Command failed: ${response.error_code} - ${response.message}`);
      }
    }
  }
});

Command Pattern Features:

• Event-based discrimination (event: "command" and event: "command_response")
• Correlation IDs for request/response tracking
• Command name validation (lowercase snake_case)
• Flexible parameters object for command-specific data
• Priority field for queue management
• Success boolean and error codes in responses
• Latency tracking for performance monitoring

Standardize MQTT-to-mesh protocol bridging for seamless integration with ESP32/ESP8266 mesh networks:

import { validators, isMeshBridgeMessage } from '@alteriom/mqtt-schema';

// Gateway bridges painlessMesh message to MQTT
const meshBridge = {
  schema_version: 1,
  message_type: 603, // MESH_BRIDGE
  device_id: 'GW-MESH-01',
  device_type: 'gateway',
  timestamp: new Date().toISOString(),
  firmware_version: 'GW 3.2.0',
  event: 'mesh_bridge',
  mesh_protocol: 'painlessMesh',
  mesh_message: {
    from_node_id: 123456789,  // painlessMesh uint32 node ID
    to_node_id: 987654321,
    mesh_type: 8,              // painlessMesh SINGLE message
    mesh_type_name: 'SINGLE',
    payload_decoded: {
      // Decoded MQTT v1 message from mesh node
      schema_version: 1,
      device_id: 'MESH-NODE-123456789',
      device_type: 'sensor',
      timestamp: '2025-10-23T20:30:00.000Z',
      firmware_version: 'SN 2.0.0',
      sensors: {
        temperature: { value: 22.5, unit: 'C' }
      }
    },
    rssi: -72,        // Signal strength
    hop_count: 2      // Hops from source to gateway
  }
};

const result = validators.meshBridge(meshBridge);
if (result.valid && isMeshBridgeMessage(meshBridge)) {
  // Process mesh message with full context
  console.log(`Mesh message from node ${meshBridge.mesh_message.from_node_id}`);
  console.log(`Signal: ${meshBridge.mesh_message.rssi} dBm, Hops: ${meshBridge.mesh_message.hop_count}`);
  
  if (meshBridge.mesh_message.payload_decoded) {
    // Process decoded MQTT v1 message
    const innerMessage = meshBridge.mesh_message.payload_decoded;
    console.log('Decoded sensor data:', innerMessage.sensors);
  }
}

Mesh Bridge Features:

• Multi-Protocol Support: painlessMesh, ESP-NOW, BLE Mesh, Thread, Zigbee
• Dual Payload Format: Raw (base64/hex) and decoded MQTT v1 messages
• Network Observability: RSSI, hop count, mesh timestamps
• Gateway Context: Gateway node ID and mesh network identifier
• Standardized Translation: Consistent format across different mesh protocols

Use Cases:

• Bridge ESP32 painlessMesh networks to cloud MQTT
• Integrate ESP-NOW devices without direct WiFi
• Heterogeneous mesh gateway (multiple mesh protocols)
• Mesh network debugging and visualization
• Low-power mesh sensor networks with cloud backend

PainlessMesh Integration Pattern:

// ESP32 Gateway Firmware (C++)
void onMeshReceive(uint32_t from, String &msg) {
  // Wrap painlessMesh message in MQTT envelope
  StaticJsonDocument<1024> bridgeMsg;
  bridgeMsg["schema_version"] = 1;
  bridgeMsg["message_type"] = 603;
  bridgeMsg["device_id"] = "GW-MESH-01";
  bridgeMsg["device_type"] = "gateway";
  bridgeMsg["event"] = "mesh_bridge";
  bridgeMsg["mesh_protocol"] = "painlessMesh";
  
  JsonObject meshMsg = bridgeMsg.createNestedObject("mesh_message");
  meshMsg["from_node_id"] = from;
  meshMsg["to_node_id"] = mesh.getNodeId();
  meshMsg["raw_payload"] = base64::encode(msg);
  meshMsg["rssi"] = mesh.getRssi(from); // If available
  
  // Try to decode as MQTT v1 message
  StaticJsonDocument<512> decoded;
  if (deserializeJson(decoded, msg) == DeserializationError::Ok) {
    meshMsg["payload_decoded"] = decoded;
  }
  
  // Publish to MQTT broker
  String bridgeJson;
  serializeJson(bridgeMsg, bridgeJson);
  mqttClient.publish("alteriom/mesh/bridge", bridgeJson);
}

Track device location and deployment context for asset management and map-based visualization:

import { validators, isSensorDataMessage } from '@alteriom/mqtt-schema';

const sensorData = {
  schema_version: 1,
  device_id: 'SN456',
  device_type: 'sensor',
  timestamp: new Date().toISOString(),
  firmware_version: 'SN 2.1.0',
  // Standardized location for map visualization
  location: {
    latitude: 43.6532,
    longitude: -79.3832,
    altitude: 76.5,
    accuracy_m: 10.0,
    zone: 'warehouse_A',
    description: 'Shelf 3, Row B'
  },
  // Deployment context
  environment: {
    deployment_type: 'indoor',
    power_source: 'battery',
    expected_battery_life_days: 365
  },
  sensors: {
    temperature: {
      value: 22.3,
      unit: 'C',
      // Enhanced sensor metadata
      timestamp: '2025-10-19T20:59:58.000Z',
      accuracy: 0.5,
      last_calibration: '2025-01-15',
      error_margin_pct: 2.0,
      operational_range: { min: -40, max: 85 },
      quality_score: 0.95
    }
  },
  battery_level: 78,
  signal_strength: -65
};

const result = validators.sensorData(sensorData);
if (result.valid && isSensorDataMessage(sensorData)) {
  // Display on map using location data
  displayOnMap(sensorData.location.latitude, sensorData.location.longitude);
  
  // Show sensor health based on metadata
  if (sensorData.sensors.temperature.accuracy) {
    console.log(`Temperature accuracy: ±${sensorData.sensors.temperature.accuracy}${sensorData.sensors.temperature.unit}`);
  }
  
  // Check calibration status
  const lastCal = new Date(sensorData.sensors.temperature.last_calibration);
  const daysSinceCalibration = (Date.now() - lastCal.getTime()) / (1000 * 60 * 60 * 24);
  if (daysSinceCalibration > 365) {
    console.warn('Sensor calibration overdue');
  }
}

Location & Environment Features:

• GPS coordinates (latitude, longitude, altitude) with accuracy tracking
• Zone-based organization (warehouses, floors, rooms)
• Human-readable location descriptions
• Deployment type tracking (indoor/outdoor/mobile)
• Power source information for battery management
• Per-sensor timestamps for async polling scenarios
• Sensor accuracy and calibration tracking
• Operational range validation support

Comprehensive system health monitoring for gateways:

import { validators, isGatewayMetricsMessage } from '@alteriom/mqtt-schema';

const metrics = {
  schema_version: 1,
  device_id: 'GW002',
  device_type: 'gateway',
  timestamp: new Date().toISOString(),
  firmware_version: 'GW 1.4.0',
  metrics: {
    uptime_s: 86400,
    cpu_usage_pct: 15.3,
    memory_usage_pct: 42.7,
    temperature_c: 45.2,
    // Enhanced storage metrics
    storage_usage_pct: 45.2,
    storage_total_mb: 512,
    storage_free_mb: 280.5,
    // Network bandwidth tracking
    network_rx_kbps: 125.4,
    network_tx_kbps: 89.3,
    active_connections: 5,
    // System health indicators
    error_count_24h: 3,
    warning_count_24h: 12,
    restart_count: 2,
    last_restart_reason: 'firmware_update',
    // Mesh network metrics
    connected_devices: 12,
    mesh_nodes: 8,
    packet_loss_pct: 0.5
  }
};

const result = validators.gatewayMetrics(metrics);
if (result.valid && isGatewayMetricsMessage(metrics)) {
  // Storage monitoring
  if (metrics.metrics.storage_usage_pct > 80) {
    console.warn('Storage usage critical:', metrics.metrics.storage_usage_pct);
  }
  
  // Network health
  const totalBandwidth = metrics.metrics.network_rx_kbps + metrics.metrics.network_tx_kbps;
  console.log(`Total bandwidth: ${totalBandwidth.toFixed(1)} kbps`);
  
  // Error trend analysis
  if (metrics.metrics.error_count_24h > 10) {
    console.error('High error rate detected:', metrics.metrics.error_count_24h);
  }
  
  // Restart tracking
  console.log(`Last restart: ${metrics.metrics.last_restart_reason}`);
  console.log(`Total restarts: ${metrics.metrics.restart_count}`);
}

Enhanced Gateway Metrics Features:

• Storage usage tracking (percentage, total, free space)
• Network bandwidth monitoring (RX/TX rates)
• Active connection counting
• Error and warning counters (24-hour rolling window)
• Restart tracking with reason codes
• All metrics are optional for gradual firmware adoption

Comprehensive best-in-class OTA solution based on 2024 industry standards.

The package includes OTA firmware manifest schema with both rich and minimal formats, enhanced with enterprise-grade features.

Preferred: Stable alias import (v0.3.1+):

import otaManifestSchema from '@alteriom/mqtt-schema/ota-manifest';
import { OtaManifest, isRichManifest } from '@alteriom/mqtt-schema/types/ota-manifest';

Legacy: Deep path import (still supported):

import otaManifestSchema from '@alteriom/mqtt-schema/schemas/ota/ota-manifest.schema.json';

Usage example:

import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import otaManifestSchema from '@alteriom/mqtt-schema/ota-manifest';
import { OtaManifest } from '@alteriom/mqtt-schema/types/ota-manifest';

const ajv = new Ajv({ allErrors: true, strict: false });
addFormats(ajv);
const validate = ajv.compile<OtaManifest>(otaManifestSchema as any);

const manifest: OtaManifest = JSON.parse(manifestJson);
if (!validate(manifest)) {
  console.error('Invalid OTA manifest:', validate.errors);
}

Supported formats:

• Rich manifest: environment + branch + manifests object
• Minimal environment map: environment → channels mapping
• Chunk variants: structured objects or SHA256 array

Security & Authenticity:

const manifest = {
  environment: "universal-sensor",
  branch: "main",
  manifests: {
    prod: {
      build_type: "prod",
      file: "firmware-v2.0.0.bin",
      size: 456789,
      sha256: "a1b2c3...",
      firmware_version: "2.0.0",
      built: "2025-10-19T12:00:00Z",
      ota_url: "https://firmware.example.com/v2.0.0.bin",
      
      // Digital signature for authenticity
      signature: "MEUCIQDx...",
      signature_algorithm: "ECDSA-SHA256",
      signing_key_id: "prod-signing-key-2025",
      
      // Version constraints
      min_version: "1.5.0",        // Minimum version to upgrade from
      max_version: "1.9.99",       // Prevent downgrades
      
      // Release management
      release_notes_url: "https://docs.example.com/v2.0.0",
      criticality: "high",          // low | medium | high | critical
      mandatory: true,              // Must be installed
      
      // Staged rollout
      rollout_percentage: 25,       // Start with 25% of fleet
      rollout_target_groups: ["beta-testers", "early-adopters"],
      
      // Delta updates (60-90% bandwidth reduction)
      delta_from_version: "1.9.0",
      delta_patch_url: "https://firmware.example.com/patches/1.9.0-to-2.0.0.patch",
      delta_patch_size: 45678,
      delta_patch_sha256: "c3d4e5..."
    }
  }
};

Firmware Update Status Tracking:

import { validators, isFirmwareStatusMessage } from '@alteriom/mqtt-schema';

// Enhanced status tracking
const status = {
  schema_version: 1,
  device_id: "SN789",
  device_type: "sensor",
  timestamp: new Date().toISOString(),
  firmware_version: "2.0.0",
  
  status: "downloading",           // New: rolled_back, rollback_pending, rollback_failed
  progress_pct: 42,
  
  // Progress details
  download_speed_kbps: 125.5,
  bytes_downloaded: 196608,
  bytes_total: 456789,
  eta_seconds: 28,
  
  // Rollback support
  rollback_available: true,
  previous_version: "1.9.0",
  
  // Security verification
  update_type: "delta",            // full | delta | patch
  signature_verified: true,
  checksum_verified: true,
  
  // Operational context
  battery_level_pct: 85,
  free_space_kb: 2048,
  retry_count: 0
};

const result = validators.firmwareStatus(status);
if (result.valid) {
  console.log(`Download progress: ${status.progress_pct}% at ${status.download_speed_kbps} kbps`);
  console.log(`ETA: ${status.eta_seconds} seconds`);
}

OTA Best Practices:

• Security: Always use digital signatures for production firmware
• Rollback: Maintain backup partition for automatic rollback on failures
• Delta Updates: Use delta patches for bandwidth-constrained deployments (60-90% reduction)
• Staged Rollout: Start with 5-10% rollout, monitor, then expand gradually
• Version Control: Use min_version to prevent upgrades from incompatible versions
• Criticality: Mark security patches as "critical" with mandatory: true

See docs/OTA_MANIFEST.md for comprehensive guide and best practices.

import { validators, validateMessage, classifyAndValidate } from '@alteriom/mqtt-schema';

// 1. Direct validator by message kind
validators.sensorData(payload); // => { valid: boolean; errors?: string[] }

// 2. Generic function
validateMessage('sensorData', payload);

// 3. Classify unknown payload then validate
const { kind, result } = classifyAndValidate(payload);

// 4. Type guards (when available)
// if (isSensorDataMessage(payload)) { ... }

Validation result format:

interface ValidationResult {
  valid: boolean;
  errors?: string[]; // Each item contains instancePath + message
}

All Ajv validator functions are compiled once at module load. For typical web usage (tens to hundreds of validations per page/session) this is faster and simpler than on‑demand compilation. If you need custom Ajv options (e.g., different formats), open an issue—an override hook can be added without breaking changes.

schema_data.ts is auto‑generated during build. This avoids dynamic require() / import of JSON and works cleanly in both Node ESM and bundlers without JSON import assertions. The original JSON files are still published under schemas/ for tooling or documentation pipelines.

Unified configuration management for both sensors and gateways, supporting remote configuration without firmware reflashing:

import { validators, isDeviceConfigMessage, MessageTypeCodes } from '@alteriom/mqtt-schema';

// Configuration update request (from backend to device)
const configUpdate = {
  schema_version: 1,
  message_type: MessageTypeCodes.DEVICE_CONFIG, // 700
  device_id: 'SN001',
  device_type: 'sensor',
  timestamp: new Date().toISOString(),
  firmware_version: 'WEB 1.0.0',
  event: 'config_update',
  configuration: {
    sampling_interval_ms: 60000,
    power_mode: 'low_power',
    ota_config: {
      auto_update: true,
      update_channel: 'stable',
      update_check_interval_h: 24
    },
    alert_thresholds: {
      temperature: {
        min: -10,
        max: 50,
        enabled: true
      }
    }
  },
  modified_by: 'admin@example.com'
};

const result = validators.deviceConfig(configUpdate);
if (result.valid) {
  // Publish to device: alteriom/nodes/{device_id}/config
  mqttClient.publish(`alteriom/nodes/${configUpdate.device_id}/config`, JSON.stringify(configUpdate));
}

// Configuration snapshot (from device to backend)
mqttClient.subscribe('alteriom/nodes/+/config/snapshot', (message) => {
  const snapshot = JSON.parse(message);
  
  if (isDeviceConfigMessage(snapshot) && snapshot.event === 'config_snapshot') {
    // Store configuration for audit trail
    console.log('Device config:', snapshot.device_id);
    console.log('Power mode:', snapshot.configuration.power_mode);
    console.log('OTA settings:', snapshot.configuration.ota_config);
    
    // Configuration version tracking
    if (snapshot.config_version) {
      console.log('Config version:', snapshot.config_version);
      console.log('Last modified:', snapshot.last_modified);
    }
  }
});

Unified Configuration Standards:

Both sensors and gateways support consistent management:

Configuration Events:

• config_snapshot: Device reports current configuration state
• config_update: Backend requests configuration changes
• config_request: Backend queries current configuration

Key Benefits:

• Remote configuration without firmware updates
• Configuration backup and restore
• Audit trail with version tracking
• Bulk configuration deployment
• Standardized across device types

For performance optimization and standardized routing, use the optional message_type field:

⚠️ BREAKING CHANGES in v0.8.0: Gateway codes 300 (info) and 301 (metrics) have been realigned to 305 and 306 for consistency. Legacy codes 300 and 301 are automatically translated during a 6-month migration period. See Migration Guide below.

• Significantly Faster: O(1) lookup vs O(n) heuristic matching (avoids 12+ conditional checks)
• Protocol Alignment: Compatible with CoAP and MQTT-SN numeric type systems
• Clear Intent: Explicit message type declaration
• Efficient Routing: Switch-case routing in backend systems
• Backward Compatible: Falls back to heuristics if omitted

import { MessageTypeCodes } from '@alteriom/mqtt-schema';

const message = {
  schema_version: 1,
  message_type: MessageTypeCodes.SENSOR_DATA, // 200
  // ... rest of message
};

Breaking Changes:

• GATEWAY_INFO: Code 300 → 305
• GATEWAY_METRICS: Code 301 → 306

Migration Timeline (6 months):

1. Phase 1 (Months 1-3): Both old and new codes accepted. Library automatically translates 300→305 and 301→306.
2. Phase 2 (Months 4-6): Deprecation warnings logged for legacy codes.
3. Phase 3 (After 6 months): Legacy codes 300 and 301 rejected.

Action Required:

// ❌ Old code (deprecated in v0.8.0)
const message = {
  message_type: 300, // gateway_info
  // ...
};

// ✅ New code (v0.8.0+)
const message = {
  message_type: MessageTypeCodes.GATEWAY_INFO, // 305
  // ...
};

// ✅ Better: Use unified device schemas (v0.8.0+)
const message = {
  message_type: MessageTypeCodes.DEVICE_INFO, // 104
  device_role: 'gateway', // Explicit role indicator
  // ...
};

Legacy Code Translation:

The library includes LEGACY_CODE_MAP for automatic translation:

import { LEGACY_CODE_MAP } from '@alteriom/mqtt-schema';

console.log(LEGACY_CODE_MAP); // { 300: 305, 301: 306 }

// Automatic translation in classifyAndValidate()
const oldMessage = { message_type: 301, /* ... */ };
const { kind, result } = classifyAndValidate(oldMessage);
// kind === 'gatewayMetrics' (automatically translated 301→306)

HTTP Transport Support (v0.8.0+):

New transport_metadata field enables HTTP REST API integration:

const httpMessage = {
  schema_version: 1,
  message_type: 101, // DEVICE_DATA
  device_id: 'SN001',
  device_type: 'sensor',
  timestamp: new Date().toISOString(),
  firmware_version: 'SN 2.1.5',
  transport_metadata: {
    protocol: 'http',
    correlation_id: 'req-12345',
    http: {
      method: 'POST',
      path: '/api/v1/telemetry',
      status_code: 200,
      request_id: 'req-uuid-12345'
    }
  },
  sensors: { temp: { value: 22.5, unit: 'C' } }
};

sensorData, sensorHeartbeat, sensorStatus, sensorInfo (v0.7.2+), sensorMetrics (v0.7.2+), gatewayInfo, gatewayMetrics, gatewayData (v0.7.2+), gatewayHeartbeat (v0.7.2+), gatewayStatus (v0.7.2+), firmwareStatus, controlResponse, command, commandResponse, meshNodeList, meshTopology, meshAlert, meshBridge (v0.7.1+), meshStatus (v0.7.2+), meshMetrics (v0.7.2+), deviceConfig (v0.7.1+), batchEnvelope (v0.7.3+), compressedEnvelope (v0.7.3+)

v0.7.3+ Fast Path (when message_type present):

• Direct O(1) lookup using message type code (200-605, 700, 800, 810)
• Supports all 23 message types including batch_envelope, compressed_envelope, and all v0.7.2 additions
• 90% faster than heuristic matching
• Validates that structure matches declared type

Heuristics (when message_type absent - backward compatible):

• event: "command" → command (v0.5.0+)
• event: "command_response" → commandResponse (v0.5.0+)
• event: "mesh_bridge" → meshBridge (v0.7.1+)
• event: "config_snapshot", "config_update", or "config_request" → deviceConfig (v0.7.1+)
• metrics + device_type: "sensor" → sensorMetrics (v0.7.2+)
• metrics + device_type: "gateway" → gatewayMetrics
• sensors + device_type: "gateway" → gatewayData (v0.7.2+)
• sensors → sensorData
• capabilities or available_sensors → sensorInfo (v0.7.2+)
• mesh_status field → meshStatus (v0.7.2+)
• mesh_network_id + metrics → meshMetrics (v0.7.2+)
• nodes array → meshNodeList
• connections array → meshTopology
• alerts array → meshAlert
• progress_pct or OTA status keywords → firmwareStatus
• status + device_type: sensor → sensorStatus
• uptime_s + device_type: gateway + no metrics → gatewayHeartbeat (v0.7.2+)
• status: online|offline|error + device_type: gateway → gatewayStatus (v0.7.2+)
• status: ok|error (no other match) → controlResponse
• device_type: gateway → gatewayInfo
• fallback → sensorHeartbeat

Schema stability is paramount. We track two related versions:

Backward‑compatible additions: new optional properties or enums, documented in CHANGELOG. Breaking: new required fields, structural changes, or removed properties (triggers parallel v2 schema path & coordinated firmware rollout).

• Works in TS >= 5, Node >= 16, Vite / Webpack / ESBuild.
• Tree shaking: unused validators pruned when using ESM builds.
• No side effects besides Ajv instance creation.

• Optional custom Ajv injection hook
• JSON Schema → Zod conversion example
• Runtime metrics helper (count validation categories)

Issues & PRs welcome. Ensure firmware repo schemas remain the authoritative source—do not manually edit generated schema_data.ts.

Before opening a PR: Run the comprehensive validation suite:

npm run verify        # Schema sync + changelog + fixtures
npm run verify:all    # Additional schema compilation + OTA manifest validation  
npm test              # Enhanced fixture validation with detailed reporting

Available validation scripts:

• npm run test - Cross-platform fixture validation (CJS/ESM) with enhanced error reporting
• npm run test:ota - OTA manifest fixture validation
• npm run verify:schemas - Ensure schemas are synced from source directory
• npm run verify:release - Check changelog contains current version
• npm run verify:all - Comprehensive schema compilation and fixture validation

Scripts are organized by category in package.json:

• Build Scripts: build, build:cjs, build:esm, clean, etc.
• Testing & Validation: test, verify:*, etc.
• Release Management: release:prepare, wiki:generate
• Repository Metadata: metadata:* (organization compliance)

See PUBLISH_CHECKLIST.md for detailed release procedures. Quick summary:

1. Update schemas in docs/mqtt_schema/
2. Run npm run verify to ensure everything is valid
3. Use npm run release:prepare -- patch|minor|major for version bumping
4. Follow checklist for tagging and publishing

Schemas are static. No network access. Supply-chain risk minimized by keeping dependencies minimal (Ajv + formats only).

MIT

This package is published to BOTH:

• Public npm registry: https://registry.npmjs.org (primary)
• GitHub Packages registry: https://npm.pkg.github.com (mirror for visibility in repo Packages tab)

Create or update an .npmrc with a scoped registry override (auth token with read:packages required):

@alteriom:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then install normally:

npm install @alteriom/mqtt-schema ajv ajv-formats

If you omit the override, npmjs.org is used (recommended for most consumers).

• GitHub Packages listing provides provenance + quick visibility in the repo UI.
• npm remains the canonical public distribution source (faster, anonymous installs allowed).

npm view @alteriom/mqtt-schema version
npm view @alteriom/mqtt-schema version --registry=https://npm.pkg.github.com

Both should return the same version.

This repository integrates the @alteriom/repository-metadata-manager tooling to continuously validate and report on repository metadata health (description, topics, documentation signals, etc.) within the Alteriom organization standards.

Run a validation (non‑destructive):

npm run metadata:validate

Generate a detailed report:

npm run metadata:report

Configuration lives in metadata-config.json (organizationTag alteriom). Default detection is auto; adjust if repository classification needs overriding.

Workflow file: .github/workflows/metadata-compliance.yml

On each push / PR against main it will:

1. Install dependencies
2. Run metadata:validate (fails job on hard non‑compliance)
3. Always attempt a best‑effort report (metadata:report) for visibility

The workflow relies only on the default GITHUB_TOKEN for read operations. If future auto‑apply operations are desired, a token with elevated repo scope would be needed and the metadata:apply script could be wired (currently omitted to keep CI read‑only).

If you add new categories of tooling or documentation, re‑run the report to see updated recommendations. For cross‑repo analytics or policy generation, use the original project directly.

For authorized maintainers you can run adjustments via GitHub Actions:

1. Open the "Repository Metadata Apply" workflow under the Actions tab.
2. Choose whether to keep dryRun (default) or set to false to apply.
3. Run the workflow; the log will show proposed or applied changes.

Local dry‑run vs apply:

npm run metadata:apply:dry  # show what would change
npm run metadata:apply      # apply changes (requires proper permissions via GITHUB_TOKEN)

Note: Applying metadata modifies repository settings (description, topics) through the GitHub API; ensure the default token has the necessary repo scopes (in public repositories the workflow GITHUB_TOKEN normally suffices for these fields).

This repository maintains comprehensive documentation across several locations:

• CHANGELOG.md - Complete version history with breaking changes and migration guides
• ROADMAP.md - Planned features and development timeline
• CONTRIBUTING.md - Guidelines for contributing to the project
• SECURITY.md - Security policy and vulnerability reporting
• PUBLISH_CHECKLIST.md - Release process and verification steps
• API_MONITOR_GUIDE.md - Integration guide for monitoring systems
• V080_BREAKING_CHANGES.md - v0.8.0 migration guide (current)

• docs/README.md - Documentation index with quick links
• docs/mqtt_schema/ - Authoritative schema definitions, types, and fixtures
• docs/releases/ - Historical release notes and summaries
• docs/archive/ - Development history and feature implementation documents

See docs/README.md for the complete documentation structure.