Decoder Contract V1
Purpose
Section titled “Purpose”A decoder transforms a raw Network Server payload into normalized measurements.
Status
Section titled “Status”Draft.
Input Concept
Section titled “Input Concept”A decoder receives:
- Raw payload.
- Received timestamp.
- Device identity.
- Device type.
- Network Server metadata.
- Optional gateway metadata.
- Decoder configuration.
Output Concept
Section titled “Output Concept”A decoder returns:
- Zero or more measurements.
- Optional warnings.
- Structured errors if decoding fails.
Measurement Concept
Section titled “Measurement Concept”A measurement should include:
- Key.
- Value.
- Unit where relevant.
- Observed timestamp.
- Value type.
- Optional metadata.
A decoder must:
- Be deterministic.
- Avoid side effects.
- Not access the database.
- Not access the filesystem.
- Not access the network.
- Not access secrets.
- Not rely on mutable global state.
- Be versioned.
- Be tested with example payloads.
Future TypeScript Interface
Section titled “Future TypeScript Interface”The concrete TypeScript interface will be defined in
packages/telemetry-decoder-sdk.
Versioning
Section titled “Versioning”Decoder behavior changes require a new decoder version unless the change is a safe bug fix with documented impact.
Open Decisions
Section titled “Open Decisions”- Exact TypeScript interface.
- Measurement value types.
- Error structure.
- Metadata structure.
- Decoder configuration structure.