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 metadata rules (TN1xx) are skipped — they all 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.toml#

[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"

A `doi` that is not a DOI#

The other schema failure worth calling out is a [technote] doi that is not syntactically a DOI, because the DOI is the identifier every citation of the document resolves through — the “Citing this document” section, the BibTeX entry, the CITATION.cff file, and the metadata registered with DataCite all read it. The field is validated when technote.toml is parsed, so the finding names technote.doi along with the value it rejected:

[TN001] technote.toml does not conform to the schema: 1 validation error for TechnoteToml
technote.doi
  Value error, Not a DOI (10.71929). A DOI looks like 10.5281/zenodo.10385500, and may also be given as a https://doi.org/ URL.

Write the DOI in one of the accepted spellings — all three of these declare the same DOI, and Documenteer normalizes whichever you use to the bare 10.NNNN/suffix form:

technote.toml#

[technote]
doi = "10.71929/rubin/2570308"
# or
doi = "https://doi.org/10.71929/rubin/2570308"
# or
doi = "doi:10.71929/rubin/2570308"

The usual causes are a DOI that lost its suffix (10.71929 with no /… after it), a DOI pasted with surrounding text, and a Zenodo or DataCite record URL pasted in place of the DOI itself. A technote with no DOI yet is not a finding: omit the field, or leave it as the doi = "" placeholder, which is read as an unset DOI.

schema-conformance (TN001)#

Example of a failing technote#

How to fix it#

A doi that is not a DOI#

See also#

A `doi` that is not a DOI#