docling-project / docling-project/docling-core
DocLangDocSerializer's add_named_groups writes a <group name=...> attribute the real DocLang 0.7 XSD does not define
- Dominant language
- HTML
- Stars
- 282
- Forks
- 214
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 21
Description
`DocLangDocSerializer`'s `add_named_groups=True` writes a ``
attribute that isn't part of the real DocLang 0.7 XSD, so it fails
`doclang.validate(..., xsd_only=True)` with:
```
Element '{https://www.doclang.ai/ns/v0}group', attribute 'name': The attribute 'name' is not allowed.
```
## Root cause
`DocLangFallbackSerializer.serialize` (`docling_core/transforms/serializer/doclang.py`,
around the `GroupItem` branch) does, when `params.add_named_groups` is true:
```python
text_res = (
f"{DocLangVocabulary._create_group_token(name=item.name)}"
f"{head}{text_res}"
f"{DocLangVocabulary._create_group_token(closing=True)}"
)
```
`_create_group_token(name=...)` emits ``. The bundled
`doclang.xsd` (installed `doclang==0.7.3`, unchanged back through the schema's
history) defines the `group` element as:
```xml
```
No `name` attribute is declared anywhere on `group` — the schema has no
attribute of that name at all, so any value fails validation, not just
specific values (a different shape from #731: this is an *undeclared
attribute*, not an *out-of-enumeration value*).
The schema's `element_head` group **does** already define a legitimate slot
for exactly this kind of free-text annotation — the optional
`` child element:
```xml
```
but `DocLangDocSerializer` already uses `` for
`GroupItem.label` (the `GroupLabel` enum — e.g. `section`), so
`GroupItem.name` (the free-text string the field docstring calls "meant for
internal use... so the grouping survives a round trip") currently has no
schema-legal element or attribute to land in.
## Suggested fix
Either:
1. Reconcile `add_named_groups` with the real DocLang 0.7 XSD by dropping the
attribute from XML output (documenting the feature as internal/JSON-only,
never XML), or
2. Extend the DocLang spec's `group` element to declare a `name` attribute
(or a second `label`-like child) so `add_named_groups=True` output is
schema-valid.
## Repro
```python
from docling_core.transforms.serializer.doclang import DocLangDocSerializer, DocLangParams
from docling_core.types.doc.document import DoclingDocument
from docling_core.types.doc.labels import GroupLabel
doc = DoclingDocument(name="repro")
doc.add_group(name="Sheet1", label=GroupLabel.SECTION)
xml = DocLangDocSerializer(doc=doc, params=DocLangParams(add_named_groups=True)).serialize().text
print(xml) # ...
from pathlib import Path
out_path = Path("/tmp") / "repro.dclg"
out_path.write_text(xml)
from doclang.validation import validate
validate(out_path, xsd_only=True, allow_empty_namespace=True)
# raises doclang.validation.ValidationError: attribute 'name' is not allowed
```
Versions: `docling-core==2.94.1`, `doclang==0.7.3`.
Contributor guide
Research direction
Start in docling_core/transforms/serializer/doclang.py at the GroupItem branch in DocLangFallbackSerializer.serialize, then reproduce the failure with add_named_groups=True and doclang.validate(..., xsd_only=True). Compare the emitted group structure with the real DocLang 0.7 XSD and establish a schema-valid, agreed treatment for GroupItem.name.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100