schema-conformance (TN001)#
Group |
Default severity |
|---|---|
Structural |
Error |
technote.toml must conform to the technote metadata schema.
The file parsed as TOML (otherwise TN005 fires), but one or more of its tables or fields does not match what the technote package expects, so the technote cannot be built or its metadata published.
When this rule fires, the author rules (TN1xx) are skipped — they need the parsed metadata — but the requirements and content rules still run, so fix the schema problem first and re-run to see the full report.
Example of a failing technote#
The most common schema failure in older technotes is a historical author-name form.
Author names were restructured in technote 0.5, so a technote.toml like this no longer conforms:
[technote]
id = "SQR-000"
[[technote.authors]]
name = { given_names = "Jonathan", family_names = "Sick" }
internal_id = "sickj"
[TN001] technote.toml does not conform to the schema. Its [[technote.authors]] entries use the pre-technote-0.5 author name keys 'name = { given_names = "...", family_names = "..." }', which were renamed in November 2023. Use 'name = { given = "Given", family = "Family" }' instead. Run 'documenteer technote migrate' to update technote.toml to the modern format automatically. Underlying schema errors: …
The finding always ends with the underlying Pydantic schema errors, which name the offending field for failures that are not about author names.
How to fix it#
If the finding names a legacy author-name form, run the migration tool, which rewrites technote.toml to the modern format:
documenteer technote migrate
For any other schema failure, read the underlying schema errors at the end of the finding — they identify the field and constraint — and correct that field against the schema documented in Configuring the Sphinx build. For the example above, the modern form is:
[[technote.authors]]
name = { given = "Jonathan", family = "Sick" }
internal_id = "sickj"
See also#
TN005 — fires instead when the file is not valid TOML at all.
Configuring the Sphinx build — the
technote.tomlreference.Migrate legacy reStructuredText/Sphinx technical notes — migrating a legacy technote to the modern format.