llms.txt validator errors: reject or warn?
A useful validator must distinguish the proposal’s only required element from conventions that improve clarity. Otherwise it reports preferences as errors.
Last updated:
Under the v2 proposal, the H1 project or site name is the only required section. A validator should reject a missing or malformed H1 and broken file-list link syntax. It should not call an absent summary, a relative URL, or a large file invalid unless its published rules clearly define a stricter profile.
Key takeaways
- Required syntax and editorial guidance need different severities.
- 90 of 113 measured H1-first responses used a blockquote; the other 23 show that frequency is not a requirement.
- Machine-readable rule codes make CI behavior auditable.
What should be an error?
Errors should identify content that a parser cannot interpret according to the proposal. Examples include an empty file, a first meaningful line that is not an H1, an additional H1, or a file-list item that is not a Markdown link.
Line numbers and stable rule codes matter. H1_REQUIRED is actionable; “your file is bad” is not. A CI job should exit non-zero only for documented errors, not for a subjective style preference.
What should remain a warning?
The blockquote summary is optional. So are the explanatory preamble, H2 sections, notes after links, and the Optional section. A validator may recommend them where they improve comprehension, but must not rewrite the proposal.
Relative URLs deserve a warning because they can be ambiguous outside their original context, although v2 does not make absolute URLs the only syntactically possible form. File size is also contextual. A large documentation map may be intentional even when a smaller curated file would be easier to consume.
What do production files look like?
Our directory snapshot includes 113 files that return text and begin with an H1. Ninety use a blockquote summary. The median has 7 H2 sections and 76 parsed list links, while observed section counts range from 0 to 84.
Those distributions show why frequency must not be confused with validity. A common feature is not automatically required, and an uncommon but permitted structure is not automatically wrong. Inspect real examples beside the formal rules.
A transparent severity policy
Publish the exact rules, their severity, and the specification version. Separate three layers:
- Errors: the parser cannot construct the required structure.
- Warnings: allowed content may reduce portability or clarity.
- Information: operational observations such as size or missing discovery relations.
Use the free validator to see line-level diagnostics, then apply the best-practice guide for choices no syntax checker can make.
The format reference defines the grammar, while verified examples show how production files vary.
Is a missing blockquote invalid?
No. It is optional under v2, though often useful.
Is a file over 50 KB invalid?
No universal maximum appears in the proposal. Size can trigger an informational review, not an invented syntax error.
Can a valid file still be poor?
Yes. Syntax cannot determine whether the selected pages are current, relevant, or safe.