Native JSON container shorthand parsing and type boundaries
Parent: MongoDB Aggregation Pipeline · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for Native JSON container shorthand parsing and type boundaries. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- $toObject retains the last value for duplicate field names. RFC 8259 recommends unique names because receivers differ; ECMA-404 defines syntax without mandating how a programming language internalizes JSON. Last-value behavior is a MongoDB mapping rule, not a universal JSON guarantee. (high confidence) [source]
Problems, failure modes and limitations
- Implementation-derived boundary in MongoDB r8.3.0: existing BSON arrays and objects do not get identity conversions to array/object, nor native array-to-object or object-to-array conversions. The dispatch tables lack these entries and raise ConversionFailure; onError can handle that failure. This was checked in source, not by executing a server. (low confidence) [source]
Comparisons and alternatives
- A valid JSON scalar is not sufficient input for these container parsers: both document errors for "123". RFC 8259 permits top-level scalar JSON values, so this failure is an operator acceptance boundary rather than proof that scalar JSON is invalid. (high confidence) [source]
- The documented non-null inputs are a JSON-object string for $toObject, and a JSON-array string or supported subtype-9 binData vector for $toArray. Numeric input such as 123 is an unsupported conversion to array, rather than automatic singleton wrapping. (high confidence) [source]
- These shorthands parse ordinary JSON containers: Extended JSON wrappers such as $oid and $date remain nested data rather than producing their BSON special types. (high confidence) [source]
- ECMA-404 defines JSON syntax without prescribing how a programming language internalizes it. BSON type mapping and conversion acceptance must therefore come from MongoDB's contract, rather than being inferred solely from JSON syntax. (high confidence) [source]
Facts and statements
- MongoDB 8.3 introduces conversion of JSON array and object strings through $convert and the $toArray/$toObject shorthand expressions. (high confidence) (verified as of 2026-10-27) [source]
- MongoDB 8.3 introduced string-to-container conversions: {$toArray: expression} abbreviates {$convert: {input: expression, to: 'array'}}, and $toObject abbreviates the corresponding to: 'object' conversion. (high confidence) [source]
- String parsing requires strict JSON: comments and trailing commas are rejected. $toArray requires a top-level array and rejects "{}"; $toObject requires a top-level object and rejects "[]". (high confidence) [source]
- Both shorthands return null for null or missing input. Conversion failures stop the aggregation; use $convert with onError and onNull to supply explicit fallback values. (high confidence) [source]
- The documented input table for $toObject lists strings and null/missing. $toArray additionally supports subtype-9 vector binData: PACKED_BIT becomes booleans, INT8 integers, and FLOAT32 doubles. A native integer such as 123 is an unsupported array conversion. (high confidence) [source]
- JSON syntax permits escaped U+0000 in strings, but MongoDB's object conversion rejects an embedded null byte in a field name. The documented input containing a key nam\u0000e fails with 'Illegal embedded null byte'. (high confidence) [source]
- String inputs require valid JSON without comments or trailing commas, and their top-level container must match the target. Thus '{}' fails for $toArray, '[]' fails for $toObject, and the standalone string '123' fails for both. (high confidence) [source]
- Parsed integers map to BSON int within signed 32-bit range, long within signed 64-bit range, and double beyond that range; decimal-point or exponent notation maps to double. Large integers can therefore lose precision. (high confidence) [source]
Children
- No children recorded.