I’ve been doing a of of implementation work on preferred serialization, CDE and
dCBOR, part of which is an effort to provide unified documentation in QCBOR --
make it easier for QCBOR users to figure this out.
I ended up writing normative language for preferred serialization. It’s
included below. I’m sharing it to see if there’s any interest in publishing it.
It’s fine if not, but it seemed worth asking. It seems like it turned out
nicely. Also appreciate comments / corrections.
I’ve found that preferred serialization, CDE and dCBOR layer up very neatly. In
the implementation they layer nicely. It’s mostly trivial to enforce preferred
serialization and CDE on the decode side once you have dCBOR decode
enforcement. The specification / documentation also layers neatly.
Thx
LL
Preferred Serialization Normative Language
Preferred serialization encoders
Shortest-form encoding of the argument MUST be used for all major types except
7. Type 7 is for floating-point, simple values and other that have their own
rules for the argument. The shortest form encoding is:
* 0 to 23 and -1 to -24 MUST be encoded in the same byte as the major
type
* 24 to 255 and -25 to -256 MUST be encoded only with an additional
uint8_t
* 256 to 65535 and -257 to -65536 MUST be encoded only with an
additional uint16_t
* 65536 to 4294967295 and -65537 to -4294967296 MUST be encoded only
with an additional uint32_t
If maps or arrays are emitted, they MUST be definite-length (never
indefinite-length).
If text or byte strings are emitted, they MUST be definite-length (never
indefinite-length).
If floating-point numbers are emitted, the following apply:
Only the shortest of double, single or half-precision that preserves precision
MUST be emitted. That is, encoders MUST support half-precision. Positive and
negative infinity and zero MUST be represented in half-precision.
NaN payloads MUST be supported.
NaNs with payloads MUST be reduced to the shortest of double, single or
half-precision. The reduction is by shifting the payload right by the
difference in the number of significand bits between the original value and the
reduced value. The reduction is performed only if zero bits are shifted out to
the right. (This will always reduce a double or single quiet NaN to a
half-precision quiet NaN).
Preferred serialization decoders
Decoders MUST accept shortest-form encoded arguments.
If arrays or maps are supported, definite-length arrays or maps MUST be
accepted.
If text or byte strings are supported, definite-length text or byte strings
MUST be accepted.
If floating-point numbers are accepted, the following apply:
Half-precision values MUST be accepted. Double and single-precision SHOULD be
accepted.
NaN payloads MUST be accepted.
CDE Normative Langauge
CDE Encoders
MUST only emit CBOR conforming to Preferred Serialization described above.
MUST sort maps by map key. The sorting is bytes wise lexicographic order of the
encoded map keys.
CDE Decoders
MUST conform to rules for Preferred Serialization Decoders
Notes
This is largely a restatement of parts section 4, RFC 8949. The purpose of the
restatement is to increase clarity, not to redefine anything.
Duplicate map keys are never allowed in CBOR at all no matter what sort of
serialization is used. All decoders should detect duplicates and error out.
Preferred Serialization and CDE only affect serialization. They do not place
any requirements, exclusions, mappings or such on the data model layer (dCBOR
is different as it affects the data model by restricting some values).
Decoders for Preferred Serialization and CDE are NOT required to check for and
reject inputs that do not conform. They can be “liberal in what they accept”
(as long as it is well-formed and valid). Some implementations of preferred
serialization and CDE may check for conformance and reject non-compliant input
(dCBOR is different as it requires rejection of non-conforming inputs).
_______________________________________________
COSE mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/cose
