D4 · Prompt Engineering › Cluster 4 · Structure with XML Tags

4.4 · Nesting & Referencing Tags

Hierarchy Claude can point back to

CONCEPT Nest tags when content has a natural hierarchy

When your content is naturally hierarchical — a set of documents, each with a source and a body — mirror that hierarchy with nested tags. The official guidance: "Nest tags when content has a natural hierarchy (documents inside <documents>, each inside <document index="n">)." An outer container holds a repeated inner element, and each inner element can carry metadata — an index attribute, a <source>, a <title> — alongside its <document_content>.

LevelTagRole
Container<documents>Wraps the whole collection.
Item<document index="1">One document, numbered by attribute.
Metadata<source>Where the document came from.
Body<document_content>The actual text of that document.

CONCEPT Referring back — Claude can point at the hierarchy

The payoff of nesting-with-metadata is addressability: because each piece has a name (or an index), your instructions can point precisely at it, and Claude can cite it back. You can ask for "the figure from <document index="2">," and Claude can attribute a claim to document 2's <source>. Referencing tag names in the instructions (4.2) becomes far more powerful once the tags form a hierarchy you can index into.

Ask: "Compare the revenue figure in <document index="1"> with the forecast in <document index="2">, and cite each by its <source>." The nested, labelled structure makes both the request and the citation unambiguous.
🔑 Keep tags well-formed: every opened tag is closed, and children sit fully inside their parent. Malformed nesting reintroduces the ambiguity you were trying to remove.

DIAGRAM A nested document tree

flowchart TD DS["<documents>"] --> D1["<document index=1>"] DS --> D2["<document index=2>"] D1 --> S1["<source>
annual_report_2023.pdf"] D1 --> C1["<document_content>
…report text…"] D2 --> S2["<source>
competitor_q2.xlsx"] D2 --> C2["<document_content>
…analysis text…"] INS["<instructions>
refer back by index & source"] -.->|"points at"| D1 INS -.->|"points at"| D2 classDef container fill:#e7f0ff,stroke:#4a90d9,color:#123; classDef meta fill:#fff3cd,stroke:#e0a800,color:#665200; classDef task fill:#d4edda,stroke:#28a745,color:#155724; class DS,D1,D2 container; class S1,S2,C1,C2 meta; class INS task;

CODE Nested documents with metadata, referenced by index

Mirrors the official multi-document structure: an outer <documents>, each <document index="n"> carrying a <source> and <document_content> — then the instruction points back by index and asks for source citations.

<documents>
  <document index="1">
    <source>annual_report_2023.pdf</source>
    <document_content>
      {{ANNUAL_REPORT}}
    </document_content>
  </document>
  <document index="2">
    <source>competitor_analysis_q2.xlsx</source>
    <document_content>
      {{COMPETITOR_ANALYSIS}}
    </document_content>
  </document>
</documents>

<instructions>
Using <document index="1"> and <document index="2">, identify strategic advantages
and recommend Q3 focus areas. Attribute every claim to the document's <source>.
</instructions>

TRADE-OFFS Flat list vs. nested hierarchy

✅ Nested + indexed + metadata

  • Each item is addressable by index and by source
  • Claude can cite claims back to a specific document
  • Scales cleanly to many documents (see 4.5 long-context)

⚠️ One flat tag for everything

  • Simpler for a single short document
  • But: no way to say "document 2" or attribute a source
  • Deep nesting on trivial content just adds ceremony
Match nesting depth to the content's real structure — one document needs one tag; a corpus needs a container, indexed items, and per-item metadata.

EXAM TRAPS

Trap: "Nesting is always better." → Nest only when there's a natural hierarchy. A single short input doesn't need a container and index.
Trap: Omitting the index/<source> metadata. → Without it you can't reliably say "document 2" or ask Claude to cite its source; addressability is the whole point.
Trap: Malformed tags — unclosed or crossed nesting. → Broken structure reintroduces ambiguity. Every child must sit fully inside its parent, every tag closed.
Trap: Thinking index must be numeric or a special attribute. → It's just a descriptive attribute you choose; consistency matters, not a reserved name.

PRACTICE

Q1 · When should you nest XML tags?

When the content has a natural hierarchy — e.g. a collection of documents, each with a source and body. Use an outer container (<documents>) with repeated indexed items (<document index="n">) carrying metadata like <source> and a <document_content> body.

Q2 · What does adding index and <source> metadata buy you?

Addressability: your instructions can point at "document 2," and Claude can refer back and cite claims to a specific document's source — impossible with one flat, unlabelled blob.

Q3 · Give an instruction that references the nested hierarchy.

"Compare the figure in <document index='1'> with the forecast in <document index='2'>, and attribute each claim to its <source>." It names both the item (by index) and the metadata tag to cite.