On this page
Confirm the document boundary before reading fields
Record a neutral artifact ID, digest, byte offset, declared document length, observed end offset, and whether the final zero byte is present. The BSON Specification, (opens in a new tab) grammar puts a signed int32 length at the start and a zero terminator at the end. A parser that stops at a convenient object boundary can hide trailing bytes, truncation, concatenation, or an incorrect length.
The source dates in this guide use 22 October 2026 as retrieval evidence for documentation without a verified publication date. They are not publication claims. Where a verified publication date is available, it is recorded in the source ledger.
| Boundary field | Record | Stop if |
|---|---|---|
| Byte order | Little endian for typed scalar fields | A tool reports host order only |
| Document length | Declared length and calculated end | Length crosses the available bytes |
| Terminator | Observed zero byte at the declared end | A parser accepts a missing terminator |
| Element sequence | Type byte, cstring name, value span | A name contains an embedded zero |
| Trailing region | Bytes after the document | Trailing bytes are silently dropped |
| Nested document | Parent span and child span | Child length escapes the parent |
Keep a raw byte-range report beside the driver object. The report can redact field names or values while preserving offsets and type bytes. Do not paste real identifiers, message text, or binary payloads into a public worksheet.
Do not collapse datetime and timestamp into one time field
The BSON Specification, (opens in a new tab) assigns type 9 to UTC datetime, represented as an int64 count of milliseconds since the Unix epoch. Type 17 is a BSON timestamp with two uint32 parts and is described as a special internal type for replication and sharding. Record the element type before a driver turns either value into a language date, integer, or formatted string.
| Element type | Format observation | Interpretation boundary |
|---|---|---|
| UTC datetime | Type 9 and int64 millisecond value | Do not infer a timezone label from display |
| BSON timestamp | Type 17 with two uint32 parts | Do not treat it as an event datetime |
| String date | Type 2 UTF-8 text | Parse only with an explicit format policy |
| Null | Type 10 with no value bytes | Do not convert null to an epoch |
| Int64 | Type 18 signed integer | Do not assume milliseconds |
| Driver date object | Conversion result and driver version | Original type is unavailable |
Record the exact source value, conversion rule, displayed value, and timezone context as separate columns. A formatted UTC string may be useful for a reader, but it is a derivative. Preserve the raw integer and type byte so another reviewer can reproduce or challenge the conversion.
Compare numeric width, representation, and range
The BSON Specification, (opens in a new tab) defines int32 as a 32-bit signed integer, int64 as a 64-bit signed integer, double as an IEEE 754 binary floating point value, and Decimal128 as a 128-bit decimal floating point value. Those types can share a displayed number while carrying different precision, range, and rounding behavior. Record the BSON type and any driver conversion instead of comparing formatted text only.
| Review field | Record | Stop if |
|---|---|---|
| Type byte | Original numeric type | The driver type is the only evidence |
| Width | Declared bit or decimal representation | A narrow type is widened without policy |
| Exact text | Source lexical or canonical representation | Formatting rounds values before comparison |
| Special value | Null, NaN, infinity, or missing state | Special values become zero or blank |
| Array element type | Type of each nested value | Mixed types are silently coerced |
| Conversion | Driver, language, and target type | The conversion is undocumented |
Synthetic type ledger
{"document":"fixture-bson-01","fields":[{"name":"when","bson_type":"utc_datetime","raw":"fixture-int64-millis","display":"fixture-UTC"},{"name":"count","bson_type":"int64","raw":"fixture-integer"},{"name":"ratio","bson_type":"double","raw":"fixture-binary-float"},{"name":"amount","bson_type":"decimal128","raw":"fixture-decimal"}],"conversion":"not assessed"}Test driver round trips without replacing source evidence
Use a synthetic document to exercise decode, display, and re-encode paths. Capture the original type map, the language object type map, the serialized type map, and any changed values. A round trip that produces the same visible text can still change integer width, decimal representation, timestamp meaning, field order, or binary subtype.
| Round trip | Observed result | Question to resolve |
|---|---|---|
| BSON to driver object | Type map and display values | Did date or numeric types change? |
| Driver object to BSON | New element types and raw values | Was precision or null state lost? |
| Nested array | Keys and element types | Did an array become a generic document? |
| Binary subtype | Subtype and byte length | Did a UUID or sensitive subtype change? |
| Unknown extension | Kept, rejected, or normalized | Can the source be reproduced? |
| Malformed document | Error, repair, or partial parse | Was the repair retained as evidence? |
Stop when type evidence is missing
Stop conditions
- Stop if the declared document length, nested span, byte order, or terminator is inconsistent.
- Stop if a timestamp is interpreted as a datetime without a source type and conversion record.
- Stop if an int32, int64, double, or Decimal128 value is compared only after lossy display formatting.
- Stop if a driver maps null, missing, NaN, infinity, or binary subtypes to an unqualified default.
- Stop if a malformed document was repaired and the original bytes or repair decision were not retained.
- Stop before sampling real documents when field names or values expose private records or identifiers.
Pair this worksheet with the data provenance log for decoder and transformation history and the data card template for collection context. A type map does not prove data quality, ownership, privacy clearance, or permission.
For a supported non-health collection, after the owner has authority to describe the scope and a controlled metadata packet, the qualified appraisal request path may be a preparation step. It does not decode BSON, convert timezones, assess database behavior, create a quote, match a buyer, or grant a license.