Module options 

The one set of conversion options every surface speaks (#577).

ConvertOptions is the serializable, surface-neutral form of what configures a DocumentConverter: every knob of its builder plus the pipeline selection (standard | vlm) and the vlm_* settings. The CLI fills it from flags, docling-serve deserializes it from the query string / JSON body / multipart text parts, the C ABI and the wasm module take it as one JSON object, the Python and Node bindings map their keyword arguments into it — and all of them then go through the same two methods: ConvertOptions::validate (one set of rejection rules, one set of messages) and ConvertOptions::apply (one mapping onto the builder). Before this module each surface re-declared the fields, re-implemented the checks and re-mapped the names, so a new option meant edits in a dozen files and the surfaces drifted (the C ABI had no list_attachments, the Node bindings never rejected vlmMaxTokens: 0, …).

Every field is an Option: None means “not given”, and the engine’s own default — defined once, in DocumentConverter::default — applies. That is what lets docling-serve layer its three option sources (merge_options: a later layer’s Some wins, its None keeps the earlier value) and what lets a binding start from a pre-configured base converter and apply only what the caller said.

The field names are the wire names: docling-serve’s request options, the C ABI’s and the wasm module’s JSON keys, the CLI flags with _ → -, the Node options in camelCase (napi’s rename), the Python keyword arguments. The few places a surface spells one differently are recorded in OPTIONS, the table the inventory test (crates/docling/tests/options_inventory.rs) checks every surface’s documentation against — a field added here without its row, flag, kwarg or OpenAPI entry fails that test rather than shipping unreachable.

Not in here: what to emit (to, the image mode, the Pandoc API version, the chunker settings — crate::chunks::ChunkOptions) and where. Those depend on what the surface can do with the result (serve streams, the browser cannot write files, the CLI writes several formats at once), so each surface keeps its own output options next to this struct.

Structs

ConvertOptions

Conversion options as every surface accepts them — see the module docs. None everywhere is the engine’s defaults.

OptionInfo

How one option is spelled on each surface, where it differs from the wire name — the central documentation the inventory test holds every surface to. One row per ConvertOptions field (the test checks both ways).

OptionsError

A rejected option: which field, and why. The message names the field in its wire spelling (ocr_scale must be a positive number, got 0); the CLI prints it through OptionsError::cli_message, which swaps in the flag.

Enums

PipelineKind

Which conversion pipeline an option set selects.

Constants

OPTIONS

The per-surface spelling table — see OptionInfo.

Functions

cli_flag

The CLI flag for a ConvertOptions field: its OPTIONS row’s cli, else -- + the name with _ → -.

merge_options

over on top of base: every field over sets (serializes non-null) replaces base’s, every one it leaves unset keeps base’s — for any all-Option options struct, which is why docling-serve’s request struct (this one plus its output fields) merges its query / body / form layers through it without a per-field list.