ISO 9001 clause 7.5.2 as markdown frontmatter: which fields to use, and how to check them

Covers ISO 9001:2015 and the new ISO 9001:2026. For teams that keep procedures, work instructions or a knowledge base as markdown files in git, and for the AI tools that read them. Last reviewed 23 September 2026.

The short answer

ISO 9001 does not name any frontmatter fields, and it does not require any particular set of them. Clause 7.5.2 asks you to ensure appropriate identification and description, format and media, and review and approval whenever you create or update a document. What is appropriate is left to you. In a markdown file, frontmatter is one reasonable way to meet the clause:

• Identification and description. The standard gives examples, not a checklist: "a title, date, author, or reference number". Use whichever of them identify your documents consistently. One reasonable set is a reference id, a title, a date and an author, plus a one-sentence description.
• Format and media. Usually nothing per file. Markdown in a git repository is the format and the medium, so say so once in your document-control procedure.
• Review and approval for suitability and adequacy. Record who approved this version and when (approved_by, approved_at). Frontmatter records the approval. The approval itself is a pull-request review or a sign-off.

The rest of document control is clause 7.5.3: who can read and change files, backups, retention, and keeping obsolete versions out of use. Version control, for instance, is clause 7.5.3.2 c), not 7.5.2. In a docs-as-code setup, the repository and your process do that work, not frontmatter.

What clause 7.5.2 actually says

ISO 9001:2015, clause 7.5.2, Creating and updating:

When creating and updating documented information, the organization shall ensure appropriate:

a) identification and description (e.g. a title, date, author, or reference number);

b) format (e.g. language, software version, graphics) and media (e.g. paper, electronic);

c) review and approval for suitability and adequacy.

This is ISO's common text for documented information, part of the Harmonized Structure that ISO's management-system requirements standards are written to. That is why the same clause appears in ISO 30401, the knowledge-management standard.

Three things follow from that wording, and each is easy to get wrong.

1. The examples are only examples. "e.g." and "or" make a title, a date, an author and a reference number illustrations of identification, not a list you must complete. An auditor asks whether your identification is appropriate and applied consistently, usually against your own document-control procedure.
2. "Description" is not a field name. It means describing the document well enough to identify it. A one-sentence summary does that job. The Open Knowledge Format recommends a description key (OKF v0.2 §4.1); ISO names no key at all.
3. Review and approval happen when you create or update. Item c) is triggered by a change. It sets no periodic review. See Does ISO 9001 require periodic document review?

How much you document is also your call. The note to clause 7.5.1 says the extent of documented information can differ with an organization's size and activities, the complexity of its processes and the competence of its people. ISO's own guidance on the 2015 edition puts it plainly: ISO 9001 "requires (and always has required) a 'Documented quality management system', and not a 'system of documents'" (ISO/TC 176/SC 2 document N1286).

Does ISO 9001:2026 change any of this?

ISO published ISO 9001:2026, the sixth edition, on 16 September 2026. It replaces ISO 9001:2015 and that edition's 2024 amendment, and ISO says it "adopts the latest Harmonized Structure for ISO management system standards".

The 2024 Harmonized Structure keeps clause 7.5.2's three items and its examples word for word, under the title "Creating and updating documented information". Clause-by-clause comparisons published since the release report one other wording change that runs through the whole standard: the 2015 verbs "maintain" and "retain" documented information become "available as documented information" and "available as evidence of". The text quoted on this page is the 2015 wording, so check it against your copy of the 2026 edition.

Certified organizations don't have to switch overnight. Global ACI, which took over the international roles of the IAF and ILAC in January 2026, has published the transition rules. There is a three-year transition period, and organizations certified to ISO 9001:2015 have until 30 September 2029 to transition. From 31 March 2028, new accredited certifications can only be issued to ISO 9001:2026. ISO's own FAQ says certified organizations "will have to transition to the new version within the timeframe set by their certification cycle."

Field-by-field mapping

You don't need all four of ISO's identification examples. A title plus a reference id identifies a document; so does a title, a date and an author. Pick a set, write it into your procedure, and apply it to every file.

A worked example

---
id: QP-07-02
title: Control of nonconforming output
description: How we identify, segregate and disposition product that fails inspection.
type: procedure
owner: Quality Manager
author: human:j.alvarez
updated: 2026-09-18
status: stable
approved_by: human:m.okafor
approved_at: 2026-09-19T09:30:00Z
---

Every key has exactly one meaning, written down once in your document-control procedure.

• type is the one field the Open Knowledge Format requires (§4.1). ISO doesn't need it, but tools use it to route and filter documents.
• The human: prefix follows OKF's actor convention (§7). It makes it unambiguous that a person approved this version, not a tool.
• If you already use OKF, you can record the approval as a verified entry instead: verified: [{by: human:m.okafor, at: 2026-09-19T09:30:00Z}] (§5.2). Choose one place for it, not both, or the two copies will drift apart.

What frontmatter can't do: clause 7.5.3

Most of document control lives in clause 7.5.3, and very little of it belongs inside the file.

Running a whole quality system in git has real costs, and some who tried it now advise against it. OpenRegulatory, a regulatory consultancy that published a guide to running a QMS in GitHub or GitLab, now recommends against doing so; it also sells its own QMS software. Its reasons: markdown tables become unmanageable, non-technical colleagues can't work in git, and reviews only stay clean if every merge request changes one document and is merged promptly. Frontmatter works best where the documents are already markdown and the people editing them already work in git. If AI tools edit those files, see A defensible audit trail for AI-edited documentation.

Why this matters to the AI tools reading your docs

Claude Code, GitHub Copilot, Cursor and local models can all pull the markdown in your repository into their context before they act. If a file carries no identification or status, an agent can't tell the approved procedure from last year's draft sitting next to it, and it may act on whichever one it finds first.

The fields that evidence clause 7.5.2 (a title, a description, a date, an author), plus an owner, status and an approval record, are the same ones that let an agent keep to current, approved content. The Open Knowledge Format, an open specification published by Google Cloud, defines lifecycle and trust fields that agents can read: status (§5.4), stale_after (§5.5), and generated and verified (§5.2).

How to check your files

A presence check fits in a CI job. This script lists every markdown file that is missing a field your procedure requires. It exits non-zero, so it can block a pull request.

#!/usr/bin/env python3
"""Report markdown files whose frontmatter lacks document-control fields.

Usage:  python3 check_frontmatter.py path/to/docs
Exits 1 if any file is missing a field, so it can gate a pull request.
"""
import sys
from pathlib import Path

import yaml  # pip install pyyaml

# What your procedure says every controlled document carries.
# Each entry is satisfied by any one of the listed keys.
REQUIRED = {
    "reference number": ["id"],
    "title": ["title"],
    "description": ["description"],
    "date": ["updated", "date"],
    "author or owner": ["owner", "author"],
    "approval": ["approved_at"],
}
SKIP = {"index.md", "log.md"}  # OKF's reserved filenames; delete if unused


def frontmatter(path):
    """The parsed frontmatter as a dict, {} if there is none, None if it won't parse."""
    lines = path.read_text(encoding="utf-8-sig").splitlines()
    if not lines or lines[0].strip() != "---":
        return {}
    for i, line in enumerate(lines[1:], start=1):
        if line.strip() == "---":
            try:
                data = yaml.safe_load("\n".join(lines[1:i]))
            except yaml.YAMLError:
                return None
            return data if isinstance(data, dict) else {}
    return None  # opening fence with no closing fence


def filled(value):
    if isinstance(value, str):
        return value.strip() != ""
    return value not in (None, [], {})


def main(root):
    failures = 0
    for path in sorted(Path(root).rglob("*.md")):
        if path.name in SKIP:
            continue
        fm = frontmatter(path)
        if fm is None:
            print(f"{path}: frontmatter will not parse")
            failures += 1
            continue
        missing = [need for need, keys in REQUIRED.items()
                   if not any(filled(fm.get(key)) for key in keys)]
        if missing:
            print(f"{path}: missing {', '.join(missing)}")
            failures += 1
    return 1 if failures else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "."))

Edit REQUIRED to match your own procedure; the set above is one reasonable choice, not ISO's. The script treats a blank value as missing, and it flags a frontmatter block that won't parse instead of skipping it. It proves a field is filled in, not that it is true. An auditor sampling files will compare approved_at against the actual approval record.

If you'd rather not maintain a script, JidoSeal's free Self-Check runs the same kind of presence check against a fixed ladder: OKF's required type (Bronze), then title, description, a date and an owner (Silver, fields that evidence clause 7.5.2), then a lifecycle status and three review fields (Gold). Pick a folder, scan it, and it lists every file and the fields it's missing, suggests the values it can work out, and writes the ones you approve into the frontmatter (in Chrome or Edge; other browsers show a preview). The scan and the fixes are free and your files never leave your machine; only a certificate costs money. It doesn't check reference numbers or approval records, and a JidoSeal certificate is not an ISO certification.

What an auditor will still ask

• Where is the procedure that defines these fields, and what does "approved" mean in it?
• What is the approval evidence for this revision, beyond the approved_at value?
• How do you stop people, and tools, from using a superseded version?
• Who can change these files, and how would you know if the history had been rewritten?

Related questions

• Does ISO 9001 require periodic document review? No interval is set; here is how to record the cycle you choose.
• What ISO 30401 asks of a knowledge base: the same clause 7.5 in the knowledge-management standard, and what files can't show.
• A defensible audit trail for AI-edited documentation: what to record when AI tools edit these files.

Sources

• ISO 9001:2026, Quality management systems — Requirements, edition 6, published 16 September 2026: iso.org/standard/88464.html; ISO press release, 16 September 2026: iso.org/news/2026/09/ISO9001-2026
• The Harmonized Structure, clause 7.5 (2020 and 2024 texts): ISO/IEC Directives, Part 1, Consolidated ISO Supplement, Annex SL, Appendix 2, which is published as a separate Harmonized Structure text: iso.org
• ISO/TC 176/SC 2 N1286, Guidance on the requirements for Documented Information of ISO 9001:2015: iso.org (PDF)
• ISO 9001:2015 clause 7.5.2 and 7.5.3 wording as quoted by Auditor Training Online: 7.5.2, 7.5.3
• 2015 vs 2026 comparison: governancedocs.com
• Transition: Global ACI, 16 September 2026; DNV
• Open Knowledge Format v0.2 specification (Google Cloud, Apache-2.0): SPEC.md
• OpenRegulatory, GitHub QMS: We No Longer Recommend It: openregulatory.com