When a METS package will not validate or a viewer cannot render it, the fault is almost always a broken internal reference — an fptr pointing at a FILEID that does not exist, or a div whose DMDID does not match any dmdSec. METS is a container that glues descriptive, administrative, structural and file metadata together by ID; most errors are dangling IDs or out-of-order sections. This guide walks the usual failures and the fixes that hold.

What are the parts of a METS package?

METS has seven possible sections, in this required order. Only structMap is mandatory:

Section	Purpose	Required?
metsHdr	Who created the package, when	No
dmdSec	Descriptive metadata (often MODS)	No
amdSec	Administrative metadata (often PREMIS)	No
fileSec	Inventory of the actual files	No
structMap	The hierarchy tying it together	Yes
structLink	Links between structMap nodes	No
behaviorSec	Executable behaviours	No

If your sections are out of this order, the document is invalid before any IDs are even checked.

Why won't my METS file validate?

Run the schema first and read the line number — do not guess:

xmllint --noout --schema mets.xsd package.xml

The four failures I see most:

1. Dangling FILEID. A structMap fptr FILEID="img-003" but fileSec has no file ID="img-003". Fix by reconciling the ID sets.
2. Section order. fileSec placed before amdSec. Reorder to the table above.
3. Missing namespace. No xmlns="http://www.loc.gov/METS/" on the root, so nothing resolves.
4. Unescaped XML inside mdWrap. Embedded MODS must be well-formed; a stray & breaks the whole document.

How do fileSec and structMap fit together?

fileSec is the inventory; structMap is the arrangement that points into it. A minimal valid pairing for a two-page item:

<fileSec>
  <fileGrp USE="master">
    <file ID="img-001" MIMETYPE="image/tiff">
      <FLocat LOCTYPE="URL" xlink:href="images/0001.tif"/>
    </file>
    <file ID="img-002" MIMETYPE="image/tiff">
      <FLocat LOCTYPE="URL" xlink:href="images/0002.tif"/>
    </file>
  </fileGrp>
</fileSec>
<structMap TYPE="physical">
  <div TYPE="item" DMDID="dmd-1">
    <div TYPE="page" ORDER="1"><fptr FILEID="img-001"/></div>
    <div TYPE="page" ORDER="2"><fptr FILEID="img-002"/></div>
  </div>
</structMap>

Note the DMDID="dmd-1" on the item div: it must match a dmdSec ID="dmd-1" exactly, or the descriptive metadata silently detaches from the object.

How do you link descriptive and administrative metadata?

Every dmdSec and amdSec carries an ID; the structMap div references them via DMDID and ADMID:

<dmdSec ID="dmd-1">
  <mdWrap MDTYPE="MODS"><xmlData><mods xmlns="http://www.loc.gov/mods/v3">
    <titleInfo><title>Parish register, St Mary, 1650-1700</title></titleInfo>
  </mods></xmlData></mdWrap>
</dmdSec>

Root-cause tip: when descriptive metadata "disappears" in a viewer, check that the DMDID on the div matches the dmdSec ID — case-sensitive, no typos.

How do you fix a package that renders out of order?

If pages appear shuffled, the ORDER attributes are missing or wrong. Viewers sort by ORDER, not document position. Add explicit ORDER="1", ORDER="2" … and, for human-facing labels, ORDERLABEL and LABEL (e.g. recto/verso, folio numbers). Never rely on file naming alone.

What is a quick validation checklist?

Before you ship a METS package, confirm:

• Sections in canonical order; structMap present.
• Every fptr FILEID resolves to a file ID in fileSec.
• Every DMDID/ADMID resolves to a dmdSec/amdSec ID.
• Each div has an ORDER if sequence matters.
• Embedded MODS/PREMIS is itself schema-valid (validate it separately).
• FLocat paths resolve relative to the package root.

Key Takeaways

• METS is an ID-linked container; most failures are dangling FILEID/DMDID references.
• Only structMap is mandatory; all sections must appear in canonical order.
• fileSec is the inventory, structMap is the arrangement that links to it via fptr.
• Link descriptive/administrative metadata with case-sensitive DMDID/ADMID attributes.
• Out-of-order rendering means missing or wrong ORDER attributes.
• Validate the wrapper and the embedded MODS/PREMIS separately.
• Always run xmllint --schema mets.xsd and fix by line number, not by guesswork.

Frequently Asked Questions

What are the main sections of a METS document?

A METS document has up to seven sections: metsHdr, dmdSec (descriptive), amdSec (administrative), fileSec (the files), structMap (the structure, the only mandatory one), structLink and behaviorSec. structMap is required; the rest are used as needed.

Why won't my METS file validate?

The most common causes are a broken FILEID or DMDID reference, sections in the wrong order, a missing namespace declaration, or an fptr that points to a file ID that does not exist in fileSec. Validate against the METS XSD to get the offending line.

What is the difference between fileSec and structMap?

fileSec lists the actual digital files with IDs and locations; structMap describes the intellectual or physical hierarchy and links to those files by FILEID via fptr elements. fileSec is the inventory, structMap is the arrangement.

Is structMap really mandatory in METS?

Yes. structMap is the only required section of a METS document. A METS file with no structMap is invalid even if it carries rich descriptive and administrative metadata.

How do I link descriptive metadata to a structMap node?

Put an ID on the dmdSec, then reference it from the matching div in the structMap using the DMDID attribute. The IDs must match exactly, including case.

Can METS contain PREMIS and MODS together?

Yes. That is the normal pattern: MODS goes in a dmdSec (wrapped in mdWrap), PREMIS goes in the amdSec, and the structMap ties them to the files in fileSec.

Related reading

• Apply PREMIS preservation metadata
• Create MODS records for digitised items
• Embedded vs sidecar metadata
• BagIt packaging for transfer
• The OAIS reference model explained