Repository navigation
feat(api): expose PDF heading hierarchy options in ConvertDocumentOptions - #756
Merged
edeandrea merged 3 commits intoOct 22, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The derived JSON flag breaks strict Jackson 2 round-trips, and the reordered imports violate the enforced formatting configuration.
2 open issues
What changed in this PR
This PR exposes PDF heading hierarchy inference through the Java conversion API, addressing #754 by letting callers configure heading levels from bookmarks, numbering, and visual style.
Changes:
- Adds eight configuration fields in
HeadingHierarchyOptionsand derives the enable flag from its presence inConvertDocumentOptions. - Adds builder and copying tests, plus a real-container PDF hierarchy test.
- Documents the new conversion capability.
| File | Description |
|---|---|
| docs/src/doc/docs/whats-new.md | Announces heading hierarchy support. |
| docs/src/doc/docs/docling-serve/serve-api.md | Lists the new conversion option. |
| docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java | Tests inferred heading levels using a PDF. |
| docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/convert/request/options/HeadingHierarchyOptionsTests.java | Tests configuration builders, getters, and immutability. |
| docling-serve/docling-serve-api/src/test/java/ai/docling/serve/api/convert/request/options/ConvertDocumentOptionsTests.java | Tests hierarchy enablement and copying. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/options/HeadingHierarchyOptions.java | Defines heading inference configuration. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/options/ConvertDocumentOptions.java | Adds hierarchy options and the derived JSON enable flag. |
Review effort: Balanced
edeandrea
force-pushed
the
feature/heading-hierarchy-options
branch
from
October 22, 2026 16:10
6b05da2 to
5b6f6e9
Compare
:java_duke: JaCoCo coverage report
|
|
||||||||||||||||||||||||||||||||||
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
edeandrea
changed the title
edeandrea
force-pushed
the
feature/heading-hierarchy-options
branch
from
October 22, 2026 16:21
5b6f6e9 to
2de081d
Compare
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
…ions Introduce HeadingHierarchyOptions with all docling-serve fields except enabled (which is derived from the presence of this options object). Add a derived doPdfHeadingHierarchy() getter that returns true when headingHierarchyOptions is non-null. Add unit tests for both options classes and a real-client integration test that verifies heading levels are inferred from PDF numbering. Update serve-api.md documentation to list the new option. Closes docling-project#754 Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>
Add feature note for HeadingHierarchyOptions in the Docling Serve section of what is new. Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>
…options The flag is derived from headingHierarchyOptions and has no builder setter, so reading serialized options back would otherwise fail on the unknown property. Also fix two Javadoc links to the Lombok getters. Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>
edeandrea
force-pushed
the
feature/heading-hierarchy-options
branch
from
October 22, 2026 16:44
743d355 to
db7421d
Compare
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
Contributor
|
🎉 This issue has been resolved in |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expose Docling's
HeadingHierarchyOptionsin the docling-java API so callers can enable PDF section-header level inference from bookmarks, outline numbering and visual style.What changed
HeadingHierarchyOptions(new)useBookmarks,useNumbering,useStyle,useFontStyle,styleSizeTolerance,numberingSchemes,maxLevel,bookmarkMatchThresholdenabledfield — the presence ofheadingHierarchyOptionsonConvertDocumentOptionsis the switchConvertDocumentOptions(modified)headingHierarchyOptionsfield (serialises aspdf_heading_hierarchy_options)doPdfHeadingHierarchy()getter — returnstruewhen options are non-null,falseotherwise@Builderno longer has adoPdfHeadingHierarchyparameterTests
HeadingHierarchyOptionsTests— builder, getters, immutability, toBuilderConvertDocumentOptionsTests— with/without hierarchy, toBuilder preservationAbstractDoclingServeClientTests.shouldInferHeadingHierarchyFromPdfNumbering— real-container test that converts a PDF with numbering and asserts multiple distinct heading levels are assignedDocs
whats-new.md(Docling Serve section)serve-api.mdoptions listCloses #754