Skip to main content

Module json

Module json 

Source
Available on crate feature json only.
Expand description

JSON parse options for protobuf JSON deserialization.

The protobuf JSON spec says parsers should reject unknown fields by default but may provide an option to ignore them. This module exposes that option, matching the per-call semantics of C++ and Java reference implementations.

The options here are runtime ones: unknown enum values (JsonParseOptions::ignore_unknown_enum_values), unregistered extension keys (JsonParseOptions::strict_extension_keys) and google.protobuf.Any @type values without a / (JsonParseOptions::strict_any_type_urls). Unknown field names are not governed here: generated deserializers ignore them unless the code was generated with buffa_build::Config::deny_unknown_json_fields (or its path-scoped deny_unknown_json_fields_in).

§Two mutually exclusive APIs: scoped (std) vs global (no_std)

Serde’s Deserialize trait has no context parameter, so runtime options must be passed through ambient state. The available mechanism differs between std and no_std builds — each build exposes exactly one:

BuildMechanismAPIScoping
stdThread-localwith_json_parse_optionsPer-closure, nestable, per-thread
no_stdAtomicPtr to leaked Boxset_global_json_parse_optionsProcess-wide, set-once

The two APIs do not interact. set_global_json_parse_options is only compiled in no_std builds; with_json_parse_options only in std.

§std: scoped per-closure options

ⓘ
use buffa::json::{JsonParseOptions, with_json_parse_options};

let opts = JsonParseOptions::new().ignore_unknown_enum_values(true);
let msg = with_json_parse_options(&opts, || {
    serde_json::from_str::<MyMessage>(json_str)
});
// Options revert to defaults here. Concurrent threads are independent.

§no_std: global set-once options

ⓘ
use buffa::json::{JsonParseOptions, set_global_json_parse_options};

// Call ONCE during startup (e.g. in your init function).
set_global_json_parse_options(
    &JsonParseOptions::new().ignore_unknown_enum_values(true)
);

// All subsequent JSON deserialization uses these options.
let msg: MyMessage = serde_json::from_str(json_str)?;

The global setter is idempotent for identical options — calling it multiple times with the same configuration is a no-op, so initialization from multiple modules is safe as long as they agree. Calling it with different options after the first call triggers a debug_assert! (panic in debug builds; the second call is silently ignored in release). Treat the first successful call as locking in behaviour for the process lifetime.

§What ignore_unknown_enum_values changes for each kind of field

The option covers enum values that the enum does not declare. With the option set, a generated message type handles such a value as the table says, in std and no_std builds alike unless a cell names the build:

FieldUnknown nameUndeclared number, closed enum
implicit presence, or requireddefault value (0 for an open enum)parse error
explicit presence (the Rust type is Option)left unsetleft unset
repeated or mapelement or entry droppedelement or entry dropped
oneof member, open enummember set, with value 0 (std); parse error (no_std)does not apply
oneof member, closed enumparse errorparse error
extensionparse errorkept

An undeclared number is an integer in the i32 range that the enum does not declare. An open enum keeps one as EnumValue::Unknown in every kind of field. With the option off, each cell is a parse error, and an extension still keeps the number.

A value that cannot be an enum value is a parse error in every kind of field, with the option on or off. Such a value is a bool, an object, an array, a number written with a fraction or an exponent (such as 1.0), or an integer outside the i32 range. A null element of a repeated closed enum field, or a null value in a closed enum map, is a parse error in both modes. For open enums, it is read as the enum’s default value.

The option applies to generated message types. JSON parsing of a DynamicMessage in buffa-descriptor does not read the option, and an unknown enum name is a parse error there.

Structs§

JsonParseOptions
Options controlling protobuf JSON parsing behavior.

Functions§

with_json_parse_optionsstd
Run a closure with the given parse options active.