Packed Sensor Object Notation (PSON)

1.1. Purpose

PSON is a binary serialization format that provides a compact, self-describing encoding for structured data. It is designed as a drop-in binary replacement for JSON in environments where bandwidth and processing resources are limited -- particularly IoT devices, embedded systems, and constrained networks.¶

PSON has been deployed in production IoT systems since 2015 as the native encoding format of the Thinger.io platform, processing sensor data across thousands of connected devices. This specification formalizes the encoding that has been validated through a decade of production use.¶

1.2. Background

IoT devices frequently exchange structured data: sensor readings, configuration parameters, device metadata, and command payloads. JSON [RFC8259] is the de facto standard for structured data interchange but imposes significant overhead on constrained devices:¶

• Verbose encoding: Field names and values are repeated as text in every message.¶
• Parsing cost: Text parsing requires string-to-number conversion and delimiter scanning.¶
• Size inefficiency: Common IoT values like small integers, booleans, and short strings are disproportionately expensive in JSON.¶

PSON addresses these issues through a binary encoding that preserves JSON's self-describing nature while dramatically reducing wire size and parsing complexity.¶

1.3. Relationship to CBOR

PSON shares structural similarities with CBOR [RFC8949]. Both use a tag byte with 3 bits for type identification and 5 bits for an inline value. However, PSON and CBOR make different design trade-offs reflecting different goals: CBOR is a general-purpose binary encoding designed for broad applicability; PSON is a minimal encoding designed specifically for integration with the IOTMP protocol on constrained IoT devices.¶

Protocol-Encoding Integration. PSON's primary design motivation is architectural. PSON and the IOTMP protocol share identical encoding primitives: the same tag-byte structure (3-bit type + 5-bit inline value) and the same varint encoding for variable-length integers. A single encoder/decoder implementation on a constrained device serves both the protocol framing layer and the application data layer. Adopting CBOR would require maintaining two independent type systems -- CBOR's major types alongside IOTMP's own field encoding -- increasing code size and complexity for no functional benefit on these devices.¶

Reduced Scope. CBOR is designed to cover a wide range of use cases through extensibility mechanisms that add implementation complexity:¶

• Semantic tags (CBOR major type 6): Over 350 IANA-registered tags for dates, bignums, decimal fractions, URIs, regular expressions, and more. Each tag number can be 1-9 bytes. Decoders must handle unknown tags gracefully. PSON has no semantic tag system -- the 8 wire types cover all data types needed for IoT applications.¶
• Indefinite-length encoding: CBOR allows arrays, maps, and strings of unknown length at encode time, terminated by a break stop code (0xFF). This roughly doubles the decoder's state machine complexity. PSON requires definite lengths, which is sufficient for IoT data that is typically fully known in memory before encoding.¶
• Half-precision floats (IEEE 754 binary16): CBOR supports 16-bit, 32-bit, and 64-bit floats, with a preferred serialization rule that requires testing each value against all three sizes. Most platforms lack native float16 support, requiring dedicated conversion routines. PSON supports only 32-bit and 64-bit floats -- the two sizes natively available on all target platforms.¶
• Simple values: CBOR defines a 256-value extensible space for simple values (currently: false, true, null, undefined, plus unassigned slots). PSON defines exactly three discrete values: false, true, and null.¶
• Arbitrary map key types: CBOR allows any data type as a map key (integers, arrays, nested maps). PSON restricts map keys to strings, matching JSON's object model and simplifying decoder implementation.¶

Wire Size. In terms of encoded size, PSON and CBOR produce comparable results for typical IoT data. PSON encodes unsigned integers 0-30 in a single byte (vs. CBOR's 0-23), providing a modest advantage for values 24-30. For most payloads, the size difference between PSON and CBOR is negligible. The justification for PSON is not superior compression -- it is the reduced implementation complexity and the shared encoding primitives with IOTMP.¶

Byte Ordering. CBOR encodes all multi-byte values in big-endian (network byte order). PSON uses little-endian for floating-point values, matching the native byte order of virtually all IoT microcontrollers (ARM Cortex-M, ESP32, RISC-V). See Section 7.¶

1.4. Relationship to MessagePack

MessagePack [MessagePack] is another binary encoding with similar goals. Like CBOR, it uses big-endian byte ordering and a more complex type system (with multiple fixed-width integer sizes and format families). PSON's simpler tag-byte design and varint-based overflow mechanism result in a smaller and more uniform implementation.¶

6.1. Unsigned Integers (Wire Type 0)

Unsigned integers represent non-negative whole numbers.¶

• Values 0-30: Encoded in a single byte: (0 << 5) | value.¶
• Values >= 31: Tag byte is 0x1F, followed by the value encoded as a varint Section 8.¶

Examples:¶

6.2. Signed Integers (Wire Type 1)

Negative integers are encoded using wire type 1 with the absolute value. Decoding: negate the stored value.¶

• Values -1 to -30: Single byte: (1 << 5) | abs(value).¶
• Values <= -31: Tag byte 0x3F, followed by the absolute value as a varint.¶

Zero and positive integers MUST use wire type 0 (unsigned_t). Wire type 1 is exclusively for negative values. Encoding zero as signed_t (tag byte 0x20) is invalid and a decoder MUST treat it as an error.¶

Examples:¶

6.3. Floating-Point Numbers (Wire Type 2)

IEEE 754 [IEEE754] floating-point values. The inline value selects the precision:¶

Inline values 2-30 are reserved for future use. Inline value 31 (varint extension) is not used for this wire type. A decoder that encounters inline value 31 or any reserved inline value (2-30) for this wire type MUST treat it as a decode error.¶

Negative zero: IEEE 754 defines negative zero (-0.0) as distinct from positive zero (+0.0). Encoders MUST encode -0.0 as a floating-point value (wire type 2), not as unsigned integer zero (wire type 0). Decoders MUST preserve the sign of zero when converting from PSON to IEEE 754.¶

NaN and Infinity: Encoders MUST encode NaN and Infinity values as 32-bit or 64-bit floats (wire type 2). These values MUST NOT be promoted to integers. Encoders SHOULD use a canonical NaN representation (quiet NaN with all-zero payload) when the specific NaN payload is not significant.¶

Examples:¶

6.4. Discrete Values (Wire Type 3)

Boolean and null values.¶

Inline values 3-30 are reserved for future use. Inline value 31 (varint extension) is not used for this wire type. A decoder that encounters inline value 31 or any reserved inline value (3-30) for this wire type MUST treat it as a decode error.¶

6.5. Strings (Wire Type 4)

UTF-8 encoded text strings. The inline value (or subsequent varint if inline = 31) indicates the byte length of the string. The string bytes follow immediately, with no null terminator.¶

• Strings of 0-30 bytes: Single tag byte with inline length, followed by the string bytes.¶
• Strings of >= 31 bytes: Tag byte 0x9F, followed by a varint length, followed by the string bytes.¶

Implementations MUST encode strings as valid UTF-8. A decoder that encounters invalid UTF-8 sequences SHOULD treat it as a decode error.¶

Examples:¶

6.6. Binary Data (Wire Type 5)

Raw binary (opaque byte sequences). Encoding is identical to strings: the inline value (or varint) indicates byte length, followed by the raw bytes.¶

• 0-30 bytes: Single tag byte with inline length, followed by data.¶
• >= 31 bytes: Tag byte 0xBF, followed by a varint length, followed by data.¶

Unlike strings, binary data has no encoding requirement (no UTF-8 constraint).¶

6.7. Maps / Objects (Wire Type 6)

Key-value maps (equivalent to JSON objects). The inline value (or varint) indicates the number of key-value pairs.¶

Each entry consists of:¶

1. A PSON string (the key). Map keys MUST be strings.¶
2. A PSON value (any wire type, including nested maps and arrays).¶

• 0-30 entries: Single tag byte with inline count.¶
• >= 31 entries: Tag byte 0xDF, followed by a varint count.¶

Key ordering: PSON does not define a canonical key ordering. However, implementations SHOULD preserve insertion order to support use cases where iteration order is significant (e.g., compact streaming mode in IOTMP).¶

Duplicate keys: A PSON map SHOULD NOT contain duplicate keys. A decoder that encounters duplicate keys SHOULD reject the map or use the last value for the duplicated key. The behavior for duplicate keys is undefined and implementations MUST NOT rely on it.¶

Example -- {"temp": 25, "hum": 60}:¶

C2                  # map_t, 2 entries
  84 74 65 6D 70    # string "temp" (key, 4 bytes)
  19                # unsigned 25 (value)
  83 68 75 6D       # string "hum" (key, 3 bytes)
  1F 3C             # unsigned 60 (varint)

Total: 13 bytes. Equivalent JSON {"temp":25,"hum":60} = 20 bytes (35% savings).¶

6.8. Arrays (Wire Type 7)

Ordered sequences of values (equivalent to JSON arrays). The inline value (or varint) indicates the number of elements.¶

Each element is a PSON-encoded value (any wire type).¶

• 0-30 elements: Single tag byte with inline count.¶
• >= 31 elements: Tag byte 0xFF, followed by a varint count.¶

Example -- [1, 2, 3]:¶

E3                  # array_t, 3 elements
  01                # unsigned 1
  02                # unsigned 2
  03                # unsigned 3

Total: 4 bytes. Equivalent JSON [1,2,3] = 7 bytes (43% savings).¶

8.1. Encoding Algorithm

• Each byte uses bits [6:0] for data (7 bits per byte).¶
• Bit [7] is a continuation flag: set (1) if more bytes follow, clear (0) for the last byte.¶
• Least significant group comes first (little-endian byte order).¶

8.2. Examples

8.3. Maximum Varint Size

Implementations MUST support varints up to 10 bytes, representing values up to 2^64 - 1 (the full uint64 range). A 64-bit unsigned integer requires at most 10 varint bytes (ceil(64/7) = 10). A receiver that encounters a varint that does not terminate within 10 bytes MUST treat it as a decode error and discard the data.¶

10.1. Float-to-Integer Promotion

When encoding a floating-point number that has no fractional part and whose absolute value fits within the uint64 range (0 to 2^64-1), implementations SHOULD encode it as an unsigned integer (wire type 0) or signed integer (wire type 1) instead of a float (wire type 2). This saves 3-7 bytes per value and exploits the fact that many IoT sensor readings are whole numbers (e.g., humidity percentages, relay states, counters).¶

This promotion MUST NOT be applied to negative zero (-0.0), NaN, or Infinity values.¶

A decoder that receives an integer where a float was expected MUST convert it to the appropriate floating-point type. This promotion is transparent to the application.¶

Size savings:¶

Note: CBOR's core specification ([RFC8949], Section 4.2.2) treats float-to-integer promotion as optional and application-dependent. PSON follows the same approach: this optimization is RECOMMENDED but not required for conformance.¶

10.2. Precision Selection

When encoding a floating-point value that requires fractional precision, implementations SHOULD choose 32-bit float (inline value 0) when the float32 representation of the value is identical to the original float64 value. Otherwise, 64-bit double (inline value 1) MUST be used. This saves 4 bytes per value.¶

More precisely: an encoder SHOULD encode a float64 value v as float32 if and only if (float64)(float32)v == v (the round-trip through float32 preserves the exact value).¶

12.1. Simple Sensor Reading

JSON: {"temperature": 23.5, "humidity": 60}¶

C2                        # map_t, 2 entries
  8B 74 65 6D 70 65 72 61 # string "temperature"
     74 75 72 65           #   (key, 11 bytes)
  40 00 00 BC 41           # float 23.5 (32-bit, LE)
  88 68 75 6D 69 64 69     # string "humidity"
     74 79                 #   (key, 8 bytes)
  1F 3C                    # unsigned 60 (varint)

JSON size: 34 bytes. PSON size: 29 bytes. Savings: 15%.¶

12.2. Device Credentials

JSON: ["user", "device1", "secretkey"]¶

E3                        # array_t, 3 elements
  84 75 73 65 72          # string "user" (4 bytes)
  87 64 65 76 69 63 65 31 # string "device1" (7 bytes)
  89 73 65 63 72 65 74    # string "secretkey"
     6B 65 79             #   (9 bytes)

JSON size: 30 bytes. PSON size: 24 bytes. Savings: 20%.¶

12.3. Boolean Configuration

JSON: {"enabled": true, "debug": false}¶

C2                        # map_t, 2 entries
  87 65 6E 61 62 6C 65 64 # string "enabled" (7 bytes)
  61                      # true
  85 64 65 62 75 67       # string "debug" (5 bytes)
  60                      # false

JSON size: 30 bytes. PSON size: 17 bytes. Savings: 43%.¶

12.4. Nested Structure

JSON: {"gps": {"lat": 40.4168, "lon": -3.7038}, "alt": 650}¶

C2                        # map_t, 2 entries
  83 67 70 73             # string "gps" (3 bytes)
  C2                      # map_t, 2 entries (nested)
    83 6C 61 74           # string "lat" (3 bytes)
    41 85 7C D0 B3        # double 40.4168
       59 35 44 40        #   (64-bit, LE)
    83 6C 6F 6E           # string "lon" (3 bytes)
    41 FE 65 F7 E4        # double -3.7038
       61 A1 0D C0        #   (64-bit, LE)
  83 61 6C 74             # string "alt" (3 bytes)
  1F 8A 05                # unsigned 650 (varint)

JSON size: 47 bytes. PSON size: 39 bytes. Savings: 17%.¶

(Note: GPS coordinates require double precision, limiting compaction. Integer values like altitude benefit most from PSON encoding.)¶

13.1. Input Validation

Implementations MUST validate PSON data during decoding:¶

• Length bounds: String and binary lengths MUST NOT exceed the implementation's maximum Section 9. A decoder MUST NOT allocate memory based on an untrusted length field without bounds checking.¶
• Nesting depth: Deeply nested maps and arrays can cause stack overflow on constrained devices. Implementations SHOULD enforce a maximum nesting depth.¶
• Map key uniqueness: Implementations SHOULD reject maps with duplicate keys, as they may indicate an injection attempt.¶
• Varint termination: A varint that does not terminate (every byte has the continuation bit set) constitutes a denial-of-service vector. Implementations MUST enforce the maximum varint length Section 8.3.¶
• Wire type validation: A decoder MUST reject values with reserved inline values (e.g., floating_t with inline value > 1, discrete_t with inline value > 2).¶

13.2. Denial of Service

PSON data from untrusted sources can be crafted to consume excessive resources:¶

• Large allocations: A malicious length prefix can trigger large memory allocations. Implementations MUST impose application-appropriate limits and MUST NOT allocate memory based solely on untrusted length fields.¶
• Processing time: Deeply nested structures can cause excessive processing time. Depth limits Section 9 mitigate this.¶

13.3. Confidentiality

PSON does not provide encryption. When transmitting sensitive data, PSON MUST be used within an encrypted transport (e.g., TLS).¶

14.1. Media Type Registration

This specification requests registration of the following media type in the "Media Types" registry:¶

• Type name: application¶
• Subtype name: pson¶
• Required parameters: none¶
• Optional parameters: none¶
• Encoding considerations: binary¶
• Security considerations: See Section 13 of this document¶
• Interoperability considerations: PSON uses little-endian byte ordering for floating-point values, which differs from CBOR and most Internet protocols. Implementations on big-endian platforms MUST perform byte swapping when encoding and decoding floats and doubles.¶
• Published specification: This document¶
• Applications that use this media type: IoT device communication, sensor data encoding, IOTMP protocol payloads¶
• Fragment identifier considerations: N/A¶
• Contact: Alvaro Luis Bustamante, alvaro@thinger.io¶
• Change controller: IETF¶

A.1. Integer Test Vectors

A.2. Floating-Point Test Vectors

A.3. Discrete Test Vectors

A.4. String Test Vectors

A.5. Container Test Vectors

A.6. Composite Test Vector

Map {"temp": 25, "hum": 60} -- 13 bytes total:¶

C2                  # map_t, 2 entries
  84 74 65 6D 70    # string "temp" (key, 4 bytes)
  19                # unsigned 25 (value)
  83 68 75 6D       # string "hum" (key, 3 bytes)
  1F 3C             # unsigned 60 (varint)

Hex: C2 84 74 65 6D 70 19 83 68 75 6D 1F 3C¶

B.1. Source Code Size

PSON's reduced source size results from its narrower scope: 8 wire types with a single varint overflow mechanism, no semantic tags, no indefinite-length encoding, no half-precision floats, and string-only map keys.¶

B.2. Compiled Binary Size (ESP32, ESP-IDF v5.4)

All projects compiled for ESP32 using espressif/idf:v5.4 Docker image with default optimization (-Og). No networking, no TLS -- pure encoding benchmark.¶

PSON's compiled encoding code is 32% smaller than NanoCBOR and 61% smaller than TinyCBOR for identical functionality. Full image sizes differ by less than 3% because the ESP-IDF base (FreeRTOS, HAL, libc) dominates at ~190 KB.¶

NanoCBOR is the most minimal CBOR implementation available for constrained devices. The difference with TinyCBOR illustrates how CBOR's broader feature set (validation, pretty-printing, JSON conversion) increases footprint even when those features are not used by the application.¶

B.3. Encoded Wire Size

All three encodings produce comparable wire sizes for the same payload:¶

The 2-byte difference with NanoCBOR is due to CBOR's half-precision float support (IEEE 754 binary16), which PSON deliberately omits to avoid the implementation complexity of float16 conversion routines. For typical IoT payloads, wire size differences between PSON and CBOR are negligible.¶

B.4. Encoding and Decoding Performance (ESP32, 240 MHz)

All benchmarks executed on the same ESP32 hardware (Xtensa LX6, 240 MHz, single core used). Each measurement averages 1,000,000 iterations of encoding or decoding the test payload.¶

Encoding: PSON encodes approximately 2x faster than both CBOR implementations. PSON's single-pass encoder with varint overflow requires fewer branches than CBOR's fixed-width (1/2/4/8 byte) argument encoding.¶

Decoding: PSON decodes 2.8x faster than NanoCBOR and 8.9x faster than TinyCBOR. The decoder benefits from the simpler tag structure (no indefinite-length containers to check, no semantic tags to skip, no half-precision float conversion, string-only map keys). TinyCBOR's significantly slower decoding reflects its more complex parser, which must handle the full CBOR data model including container tracking and validation.¶

These performance differences are a direct consequence of PSON's reduced format complexity, not implementation quality -- NanoCBOR is a well-optimized, production-quality CBOR library specifically designed for constrained devices.¶

B.5. Summary

Note: The primary justification for PSON is not performance superiority over CBOR, but the architectural integration with the IOTMP protocol -- shared encoding primitives eliminate the need for two independent type systems on constrained devices (see Section 1.3). The performance and complexity advantages documented here are a consequence of that narrower design scope.¶