How to Read ISO Specs (Primer)

To interpret the clauses, requirements and definitions that pdf-spec-mcp returns, you need a little of the drafting convention shared by all ISO standards. This page is the minimum needed to use the PDF Family well.

1. The standard skeleton

Every ISO standard has roughly the same bones.

Section	Content	Normative?
1 Scope	What the standard applies to	Normative
2 Normative references	Other standards it cites (cited parts rank with the body text)	Normative
3 Terms and definitions	Definitions. Fixes what a term means inside this standard	Normative
4… Body (Clauses)	The requirements themselves	Normative
Annex A, B, …	Annexes. Normativity depends on the (normative) / (informative) label	Depends on label
Bibliography	Further reading	Informative

Numbering deepens as 14 (clause) → 14.9 (subclause) → 14.9.4. get_section's section parameter takes these numbers; passing a parent number returns its whole subtree.

2. Normative vs informative

Not every sentence in a standard is a requirement. Confusing the two leads to the classic accident of calling something a "spec violation" on the strength of informative text.

• NOTEs and EXAMPLEs are informative — they contain no requirements (and per the ISO/IEC Directives they must not)
• Footnotes are informative too
• Annexes are judged by the (normative) / (informative) label in their title

pdf-spec-mcp preserves this distinction structurally: in get_section output, NOTE / EXAMPLE come back as note elements separated from paragraph (body text), and get_requirements extracts normative sentences only. Never cite a note element as grounds.

3. Requirement levels — shall / should / may / can

The ISO/IEC Directives Part 2 defines the auxiliaries strictly.

Auxiliary	Meaning	Relation to conformance
shall / shall not	Requirement / prohibition	Condition of conformance. Violation = non-conformance
should / should not	Recommendation / discouragement	Not following it is not non-conformance
may	Permission	Implementer's freedom
can / cannot	Possibility / capability	Not a requirement (and not a permission either)

• Everyday-English "must" is not used in ISO normative text (it is reserved for external constraints). Requirements are always shall
• get_requirements' level maps to these five levels (shall / shall not / should / should not / may), and statistics returns counts per level
• Only shall counts in a conformance argument. Never write up a should violation as a "spec violation"

4. Definitions (Clause 3) override everyday language

Terms and definitions is a normative section that fixes what a term means inside that standard. The terms that drift furthest from everyday usage deserve the most care. Important PDF examples:

• PDF processor (3.49) / PDF reader (3.51) / PDF writer (3.52) — any active agent that writes, reads, updates or otherwise processes a PDF file, software or not. Whether a shall binds the file or the processor depends on the subject of the sentence. ISO 32000-1's conforming reader / conforming writer was replaced by these in ISO 32000-2, so quoting the older wording against a PDF 2.0 clause misnames the subject
• running text (3.59) — the body of text, as distinct from headings, footnotes, diagrams and callouts. Narrower than everyday "text"
• object (3.44) — the basic data structure of a PDF file, and exactly these 9 types (array, boolean, dictionary, integer, name, null, real, stream, string). Not "object" in the programming sense
• deprecated (3.15) — should not be written into a PDF 2.0 document and should be ignored by a PDF processor. Not "removed"

get_definitions returns Clause 3, which holds 71 entries (3.1–3.71) in ISO 32000-2. Many everyday-sounding PDF terms are not there: artifact and annotation, for instance, are defined in the body (§14.8.2.2 "Real content and Artifacts", §12.5 "Annotations"), so get_definitions finds nothing for them and search_spec / get_section is the way in. An empty result means "not in Clause 3", never "not defined". The notes attached to a definition (Note to entry) are supplements, kept separate from the definition text.

5. Watch the subject — a requirement on the file, or on the processor?

ISO 32000's shalls point in two directions.

• "The value shall be …" → a requirement on the PDF file (a validator can check the file)
• "A PDF reader shall …" (ISO 32000-1: "A conforming reader shall …") → a requirement on the processor (looking at the file cannot decide conformance)

pdf-verify can check only the former. The latter is never grounds for "this PDF violates the spec". When quoting a clause, quote it with its subject (get_requirements' text is verbatim, so it can be quoted as-is).

6. Read table-derived requirements with their context

ISO 32000 keeps many of its requirements in tables (e.g. Table 182 — Additional entries specific to text markup annotations). A cell saying "The type of annotation … shall be …" is meaningless without knowing which table and which entry it binds — that same sentence appears in several annotation tables, each binding a different set of subtypes. That is why get_requirements attaches table / key to requirements with source: "table" — quote that context along with the text. The tables themselves come back structured from get_tables.

7. Map of PDF-related standards

Standard	Content	In corpus?
ISO 32000-1 (2008)	PDF 1.7	✅ pdf17
ISO 32000-2 (2020)	PDF 2.0 (the default reference)	✅ iso32000-2
ISO/TS 32001–32005	Extension TSs (SHA-3, ECC signatures, AES-GCM, …)	✅
ISO 14289-1/-2	PDF/UA (accessibility)	✅
ISO 19005	PDF/A (long-term preservation)	❌ Outside the corpus — verdicts belong to veraPDF
ETSI EN 319 142	PAdES (long-term signatures)	❌ Outside the corpus — structural observation only (T3)

What zero search hits mean (again)

Zero hits from search_spec mean "this corpus cannot answer", NOT "no such requirement exists". PDF/A and PAdES requirements in particular will never appear here. Check coverage.gaps in list_specs.

Related pages

• pdf-spec-mcp — each tool's parameters and output
• Architecture & Responsibilities — assertion strength (T1/T2/T3), declaration / conformance / validation
• Glossary