Inconsistent naming: convert endpoints use `options`, chunk endpoints use `convert_options` for same object -- silently drops settings

[Ulli2060]

Summary

The convert and chunk endpoints accept the same ConvertDocumentsRequestOptions object, but under different field names. Combined with Pydantic's default behavior of silently ignoring unknown fields, this causes user settings to be dropped without any error or warning.

Endpoints and their field names

Convert endpoints -- field: options

Endpoint	Request model	Conversion options field
POST /v1/convert/source	ConvertDocumentsRequest	options
POST /v1/convert/source/async	ConvertDocumentsRequest	options

{
  "options": { "pipeline": "vlm", ... },
  "sources": [...]
}

Chunk endpoints -- field: convert_options

Endpoint	Request model	Conversion options field	Chunking options field
POST /v1/chunk/hybrid/source	HybridChunkerOptionsDocumentsRequest	convert_options	chunking_options
POST /v1/chunk/hybrid/source/async	HybridChunkerOptionsDocumentsRequest	convert_options	chunking_options
POST /v1/chunk/hierarchical/source	HierarchicalChunkerOptionsDocumentsRequest	convert_options	chunking_options
POST /v1/chunk/hierarchical/source/async	HierarchicalChunkerOptionsDocumentsRequest	convert_options	chunking_options

{
  "convert_options": { "pipeline": "vlm", ... },
  "chunking_options": { ... },
  "sources": [...]
}

Both options and convert_options reference the same type: ConvertDocumentsRequestOptions.

Problem

Since Pydantic BaseModel does not use extra="forbid", unknown fields are silently ignored:

1. User sends "options": { "pipeline": "vlm", ... } to a chunk endpoint
2. Pydantic silently drops options (unknown field at chunk endpoints)
3. Default ConvertDocumentsRequestOptions() is used instead
4. VLM pipeline config, OCR settings, custom prompts -- all ignored
5. No error, no warning -- request succeeds with wrong defaults

Real-world impact: I spent significant time debugging why my VLM pipeline prompt overrides were being ignored at chunk endpoints. The root cause was simply that the field is called convert_options there, not options.

Proposed solution

Option A: Rename convert_options to options (preferred)

Use options consistently at all endpoints. The chunk-specific settings are already clearly separated in chunking_options, so there is no naming conflict.

Before	After
Convert: options	Convert: options (unchanged)
Chunk: convert_options + chunking_options	Chunk: options + chunking_options

Option B: Add extra="forbid" to request models

Add model_config = ConfigDict(extra="forbid") to the base request model. This would raise a Pydantic validation error when unknown fields like options are sent to chunk endpoints, making the mistake immediately obvious.

This would be good practice regardless -- it prevents silent misconfiguration for any field name typo.

Ideally both: Rename for consistency and add extra="forbid" for safety.

Steps to reproduce

import httpx

# This works -- options is the correct field name for convert endpoints
convert_request = {
    "options": {"pipeline": "vlm"},
    "sources": [{"url": "https://example.com/doc.pdf"}]
}
r = httpx.post("http://localhost:5001/v1/convert/source", json=convert_request)
# Result: VLM pipeline is used correctly

# This SILENTLY FAILS -- options is ignored at chunk endpoints
chunk_request = {
    "options": {"pipeline": "vlm"},  # <-- silently dropped!
    "chunking_options": {"max_tokens": 512},
    "sources": [{"url": "https://example.com/doc.pdf"}]
}
r = httpx.post("http://localhost:5001/v1/chunk/hybrid/source", json=chunk_request)
# Result: default pipeline (standard) is used, VLM config silently ignored

# Correct chunk request requires convert_options instead
chunk_request_correct = {
    "convert_options": {"pipeline": "vlm"},  # <-- correct field name
    "chunking_options": {"max_tokens": 512},
    "sources": [{"url": "https://example.com/doc.pdf"}]
}

Related issues

• [BUG] can't disable OCR #468 -- [BUG] can't disable OCR (could be caused by same silent field dropping)
• 'usage.md' documentation provides incorrect parameters for sources #461 -- usage.md documentation provides incorrect parameters
• HybridChunkerOptions is used for both chunking endpoints #486 -- HybridChunkerOptions used for both chunking endpoints

Source code reference

File: docling_serve/datamodel/requests.py

# Convert endpoints use "options"
class ConvertDocumentsRequest(BaseDocumentsRequest):
    options: ConvertDocumentsRequestOptions = ConvertDocumentsRequestOptions()

# Chunk endpoints use "convert_options" for the same type
class HybridChunkerOptionsDocumentsRequest(BaseDocumentsRequest):
    convert_options: ConvertDocumentsRequestOptions = ConvertDocumentsRequestOptions()
    chunking_options: HybridChunkerOptions = HybridChunkerOptions()

Environment

• docling-serve: v1.9.x / v1.10.x
• Discovered via source code analysis of docling_serve/datamodel/requests.py

[dosubot]

You're absolutely right about the inconsistent field naming: convert endpoints use options, while chunk endpoints use convert_options for the exact same ConvertDocumentsRequestOptions object. This, combined with Pydantic's default behavior (extra fields are silently ignored), means that sending options to a chunk endpoint results in all your conversion settings being dropped with no error or warning—leading to confusing, hard-to-debug behavior. The code and recent PRs confirm this inconsistency and show that neither request model uses extra="forbid", so typos or misnamed fields go unnoticed and default settings are used instead (source).

Your proposed solutions—renaming convert_options to options for consistency, and adding extra="forbid" to all request models—would both prevent this silent misconfiguration and make mistakes immediately obvious. This is standard best practice for robust API design and would help avoid issues like those in #468, #461, and #486. There’s no evidence of technical blockers or historical reasons for the current naming, so a unified field name and strict validation would be a clear improvement.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[sawilde]

I must disagree with the honourable @dosubot, any change to the API as described above should be a considered a breaking change as existing integrations would break as they would either

1. not expecting API errors due to the server enforcing the requests through the use of extra="forbid", or
2. their requests suddenly doing what they expected as the fields have now changed names.

I feel the consistency in naming makes sense, and sure as hell less confusing, I just feel the change is a little bigger then the bot believes it to be.