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

Open
#748 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.