Nested Documents UI — Phase 5: Documentation — Nested Documents feature guide

[luis100]

Overview

Create user and developer documentation for the Nested Documents UI feature, using the EmailArchive metadata type as the worked example.

Part of: #3382

---

Scope

1. Developer Guide — How to add a new nested metadata type

A step-by-step guide covering every file that must be created or modified to introduce a new metadata schema with nested child documents:

Step	File	What to do
1	roda-core/.../config/schemas/{type}.xsd	Define XML schema with parent fields and child element type
2	roda-core/.../config/crosswalks/ingest/{type}.xslt	Write crosswalk — parent fields + nested <field name="…"><doc>…</doc></field> block
3	roda-wui/.../config/roda-wui.properties	Register type under ui.browser.metadata.descriptive.types
4	roda-wui/.../config/i18n/ServerMessages.properties	Add human-readable label ui.browse.metadata.descriptive.type.{type}=…

Include the rakenskapsinfo pattern reference and explain the XSLT namespace wildcard (*:) technique.

2. Virtual Catalogue Configuration

Explain how to create a virtual catalogue entry that queries nested children directly:

• Property keys: ui.lists.{listId}.title, ui.lists.{listId}.filter, ui.lists.{listId}.columns.*
• Filter format: ChildOfFilterParameter expression
• Column field naming: dynamic suffix convention (_txt, _s, _dt, _b, _i)
• History URL format: #search/$prefilter/title/{Label}/@{listId}
• Example: Search_emails catalogue wired to content_type:email child filter

3. Advanced Search — Nested Filter Groups

Explain how to add a nested filter group to the Advanced Search panel:

• Property keys: ui.search.fields.AIP.{groupId}.*
• Group type: NESTED vs SIMPLE
• Field path syntax for child fields: emails.subject_txt, emails.sender_s, etc.
• Link to ParentWhichFilterParameter semantics (returns parent AIP when any child matches)

4. EmailArchive Worked Example

Walk through all of the above using the EmailArchive implementation as a concrete example:

• Show the XSD structure
• Annotate the XSLT template with inline comments
• Show the resulting Solr document structure (parent + nested children)
• Show the roda-wui.properties entries for the virtual catalogue and advanced search group
• Show the history URL that opens the emails virtual catalogue

5. Testing Guide

How to test a new nested type:

• Fixture XML files to create (full, minimal, no-children edge cases)
• Constants to add to CorporaConstants
• *CrosswalkTest pattern to follow
• Running tests: mvn -pl roda-core/roda-core-tests test -Dtestng.groups=all

---

Deliverables

• documentation/Nested_Documents_Guide.md — developer guide (all sections above)
• Update documentation/Metadata_Formats.md (or equivalent) to list emailarchive as a supported type
• Add inline XSLT comments to crosswalks/ingest/emailarchive.xslt for clarity
• Update README.md or DEV_NOTES.md with a pointer to the new guide (if appropriate)

---

Notes

Note

Documentation should be written for two audiences: (1) RODA administrators who want to configure a new metadata type, and (2) developers who need to understand the underlying Solr nested document mechanics.

Important

All examples must remain generic — the EmailArchive type is an illustration only, not a special case. The guide must make clear that the pattern applies to any hierarchical metadata schema.