Define an Android CBOR Decoder Contract for Tags and Maps

Direct answer

CBOR is a binary data-interchange format whose generic data model includes unsigned and negative integers, byte strings, text strings, arrays, maps, tags, and simple/floating-point values. A decoder must not flatten every item into JSON before deciding whether the original distinctions matter. CBOR integer and floating-point values are distinct in the generic data model even when they have the same mathematical value; byte strings are distinct from text strings; and a tagged value is distinct from its untagged content. A JSON object cannot represent all these distinctions directly. RFC 8949 separates well-formedness, validity, and application expectations. Well-formedness asks whether the bytes can be parsed as CBOR items. Validity adds checks such as duplicate-key handling and tag constraints. Expected input adds the application’s schema, supported tag set, key types, ranges, and allowed operations. A well-formed item can still be invalid under a validity profile or unsupported by the application. Report these states separately; “decode succeeded” is not synonymous with “accepted data.” Map duplicate checks must follow the selected data model, not an informal numeric intuition. Under the generic model, integer `1` and floating-point `1.0` are distinct keys. Positive and negative zero compare equal for map-key equivalence. Two NaN values are equivalent when their significands are the same after zero-extension on the right to 64 bits. A tagged value is distinct from an untagged value, and byte strings are distinct from text strings. A protocol-specific data model may define additional equivalences; if an application later converts keys into a language map or JSON object, that projection can introduce collisions that were not duplicate keys under generic CBOR. Test and report the two layers separately. Decoders vary in whether they reject duplicate keys, pass every pair to the application, or retain only one value. A streaming decoder may not retain enough map state to detect duplicates. If duplicates matter to security or deterministic interpretation, use an API that exposes all pairs or rejects duplicates before collapsing them. If a generic decoder keeps only the first or last key, the application may be unable to discover what was discarded. Document the exact decoder behavior and reject ambiguous input when that behavior cannot satisfy the protocol. Tags carry semantics by numeric tag number and enclosed data item. RFC 8949 defines generic tag structure but not application meaning for every registered or private tag. Decide which tags are recognized, whether an unknown tag is rejected or preserved opaquely, and what structural and semantic validation applies to known tags. Do not strip tags before checking whether they distinguish a timestamp, big number, URI, or application-specific value. A tag number alone is not proof that its content has the required form or meaning. Deterministic encoding is a protocol profile, not an authentication feature and not one universal “canonical CBOR” byte string. RFC 8949 core deterministic requirements constrain preferred serialization, lengths, floating-point widths, definite-length items, and map-key ordering; protocols may choose additional rules, including tag presence and application-specific distinctions. The profile must state which requirements apply. Re-encoding a valid but non-deterministic item may change bytes while preserving a semantic value. Hashing or signing the original bytes and later comparing re-encoded bytes is not safe unless the signed representation/profile is explicit. Converting CBOR to JSON is a lossy projection unless the application defines a tagged wrapper scheme. JSON object keys are strings, so converting integer or compound CBOR keys into strings can collide. JSON numbers do not preserve every CBOR integer, float width, non-finite value, or negative zero distinction. CBOR byte strings need an explicit encoding such as base64; tags need a representation that preserves tag number and content. If the consumer cannot accept the original model, retain the CBOR bytes and provide a clearly labeled view instead of claiming transparent conversion. Build fixtures from RFC vectors plus application cases: integer and float keys of equal mathematical value, both signed zero forms, NaN encodings with significands that match after right zero-extension to 64 bits, byte/text keys with identical octets, tagged and untagged values, exact duplicate keys, unknown and known tags, unsupported tag content, indefinite-length items, non-preferred integer/float widths, invalid UTF-8, truncated data, deeply nested containers, and oversized byte strings. Check parser behavior, duplicate detection, tag policy, validity result, and normalized application object independently. Apply resource bounds before downstream work: total input bytes, nesting, map/array item counts, byte/text lengths, tag nesting, and elapsed time. Use the selected decoder’s limits where available, then verify them with hostile synthetic fixtures. Do not invent decoder defaults or hand-roll a CBOR parser because the preferred library lacks one control. If parsing cannot expose duplicate pairs or unknown tags needed by the contract, classify the use case unsupported or choose a library with the required API. The final report should identify RFC profile, decoder coordinates/version, duplicate-key behavior, supported tags, deterministic encoding profile, generic-model validity, application validation, and every conversion step. It must distinguish a malformed item, invalid map/tag, valid-but-unsupported item, and accepted application value. This is a method for CBOR interchange; it does not claim Cove uses CBOR, that generic CBOR tags are trusted, or that deterministic encoding authenticates the data.

A JSON projection collapses typed CBOR keys

A source CBOR map contains an integer key `1` and a floating-point key `1.0`; under RFC 8949’s generic data model these are distinct keys, not duplicates. A later JSON converter stringifies both keys as `"1"`, while a typed-pair consumer can preserve the distinction or reject that projection.

Decision

Validate duplicate keys under generic CBOR equivalence first, then test the separate host-language/JSON key projection and refuse it if two accepted source keys collapse.

Expected outcome

The importer distinguishes a valid typed CBOR map from a lossy or colliding projection and reports failure at the projection layer without labeling the original map invalid.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Pinned decoder/profile and map-pair visibility
• Signed-zero/NaN/int-float and tag fixtures
• Duplicate, validity, and projection-collision results

Task quality needs a versioned corpus and acceptance rules. Fluent sample output is not an accuracy result.

Implementation workflow

1. Pin decoder and data-model profile. Record the exact Android decoder/version, supported RFC 8949 profile, map representation, tag callback behavior, streaming mode, and parser resource controls. Verify whether map pairs remain observable before a native map collapses them.
2. Specify key equality and duplicate outcomes. Apply RFC 8949 generic key equivalence: integer `1` and float `1.0` remain distinct; signed zeros compare equal; NaNs compare equal when significands match after right zero-extension to 64 bits. Treat tagged/untagged and byte/text values under the model, then test host-language/JSON collisions separately.
3. Define supported and unknown tag behavior. Allowlist tag numbers with their required content type and semantic checks. Preserve unknown tags opaquely only when the application can retain their number and item; otherwise reject them. Never remove a tag before checking whether its meaning is required.
4. Set a deterministic encoding profile. Name the RFC deterministic requirements and any protocol additions for tags, floating-point values, negative zero, map order, and key types. Compare semantic items and encoded bytes separately; deterministic encoding is not integrity or authentication.
5. Exercise validity, conversion, and bounds. Use RFC and synthetic fixtures for duplicates, unknown tags, boundary numbers, byte/text collisions, malformed and truncated inputs, deep nesting, item counts, and decoder limits. Report well-formed, valid, expected, unsupported, and rejected outcomes distinctly.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• The report separates CBOR well-formedness, RFC/profile validity, and application-expected input instead of treating parse success as acceptance.
• Duplicate-key checks use RFC 8949 §5.6.1 generic key equivalence; integer `1` and float `1.0` are distinct there, while signed zero and NaN follow the specified equivalence rules.
• Decoder duplicate behavior, map-pair observability, tag allowlist/unknown-tag policy, and application projection collisions are tested on the exact library/version.
• The deterministic encoding profile is named and scoped; it is not presented as cryptographic integrity, authentication, or one universal canonical byte representation.
• JSON projection preserves or explicitly reports loss of tags, byte strings, numeric distinctions, and non-string keys; no silent string-key coercion is accepted.

Decision table

Failure patterns to prevent

• Calling integer and float keys generic duplicates
• Stripping unknown tags before choosing policy
• Treating deterministic encoding as authentication

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Android privacy and security
• IETF RFC 8949 — CBOR data model, validity, key equivalence, and deterministic encoding
• IANA — Concise Binary Object Representation (CBOR) Tags Registry

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions