Validation error response (422) isn't whats in OpenAPI document

[edeandrea]

The ValidationError type in the OpenAPI document:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

isn't what actually comes back from docling-serve (at least with v1.10.0):

{
  "detail" : [ {
    "type" : "missing",
    "loc" : [ "body", "sources", 0, "file", "base64_string" ],
    "msg" : "Field required",
    "input" : {
      "kind" : "file"
    }
  }, {
    "type" : "missing",
    "loc" : [ "body", "sources", 0, "file", "filename" ],
    "msg" : "Field required",
    "input" : {
      "kind" : "file"
    }
  } ]
}

The input field isn't documented. I think it used to be, but was documented as a string and now its an object, which is breaking my deserialization. My current workaround is to completely ignore the input field.

[dosubot]

The mismatch is due to how FastAPI and Pydantic v2 handle validation errors. The runtime 422 responses now include an input field (sometimes a string, sometimes an object) that shows the offending value, but this field isn't described in the OpenAPI schema generated by FastAPI. This is because the OpenAPI spec only documents fields FastAPI explicitly models, while the actual error response includes everything Pydantic emits, including input. This change came with recent dependency upgrades and is not specific to docling-serve—it's a side effect of relying on FastAPI's default error handling with Pydantic v2.10+ source.

The input field can be a string or an object, depending on what failed validation source. Since this field isn't documented in the OpenAPI schema, strict deserialization will break. The best workaround is to ignore unknown fields in your error model or use a more flexible error handler that tolerates extra fields source.

If you need to track schema changes, there’s no evidence the input field was ever formally documented in the OpenAPI spec for docling-serve, but its presence in responses is consistent with Pydantic v2+ error output source.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[edeandrea]

Thank you for the explanation. We can ignore the field going forward, but if the field is there then I presume it could be interesting for a downstream consumer to care about, especially during an error scenario.

If the input field can be one thing or another with a condition then that should be documented properly so that it can be serialized/deserialized properly by consumers.