Dify Community Proposes Structured Output Fix for Field Names That Conflict with Schema Keywords

A field-naming compatibility issue has emerged in Dify’s structured output layer. On October 29, the community reported an issue in the dify-agent main branch: when an output field is named default and uses $ref to point to a local $defs definition, agent creation may raise a KeyError. The same structure works when the field is renamed to widget, pointing to Schema traversal rather than generated model content as the source of the problem. Issue report

JSON Schema uses $defs to store reusable substructures, which can then be referenced with $ref. This is useful when multiple fields share the same object definition. These references have explicit structural semantics; a traverser must distinguish Schema keywords from user-defined field names inside properties. Official JSON Schema guide

Dify’s public code shows that the output layer first expands local references, then passes the Schema to Pydantic. When the existing traversal encounters keys such as default, enum, and const, it preserves their values and skips deeper processing. The same rule also applies to field-name mappings, which can leave references unexpanded while removing the root-level $defs, causing subsequent Schema generation to fail. Output layer code

The fix proposed on October 30 changes traversal according to context: it preserves literal data in Schema objects while processing each child Schema in field mappings. The author reported that 13 tests failed on the original version, while all 33 output-layer tests passed after applying the fix. These results have not been independently rerun, and the PR is still awaiting review. Fix proposal and tests

For engineering teams, this means that field names in existing data contracts may affect agent initialization. The report also notes that the same path may fail to check non-local references, but current evidence is insufficient to conclude that this could trigger external access. Teams using nested structured output can validate agent creation with their actual Schemas and track whether the fix is merged and included in a release.