Technical detail · CoAP API Design: Resource and Response Contracts
Format identifiers and payload-size assumptions
A CoAP resource contract specifies the format of the payload, the message’s application content, so both endpoints can interpret its bytes.
The agreed formats include text/plain (Content-Format 0) for a scalar whose meaning is known elsewhere, application/json (50) for inspectable structured text, and application/cbor (60) for structured binary data. Content-Format is the option identifying the body’s format; JSON and CBOR are the structured text and binary formats respectively. application/octet-stream (42) carries raw bytes with a layout both endpoints must agree on.
10.7.1 Interactive Payload Comparison
The example payload model uses text keys, a float64 reading, a 64-bit floating-point value, and an optional uint32 timestamp: a time attached to the reading, stored as an unsigned 32-bit integer. Its CBOR count is a model, not encoder output. Its text output carries only the value, so adding a timestamp to the structured records makes the text comparison unequal.
10.7.2 Interactive URI Analysis
Treat those counts as body bytes. They are neither total packet sizes nor battery measurements. Smaller data alone does not establish whole-device energy savings or the voltage available during a radio pulse. Likewise, a naming analyzer’s score reflects its own conventions; its URI resource-address text count is not an encoded packet size or full validity test.
Inspect the gateway diagnostic and binary schema, payload comparison model, and URI naming analyzer in the reference chapter.