CitationModel#

pydantic model documenteer.conf._toml.CitationModel#

Model for an entry in the [[project.citations]] array of documenteer.toml.

An entry carries both the work’s bibliographic fields and the presentation fields that say how the site displays it. The bibliographic fields can instead come from a CITATION.cff file, named by cff, in which case a field set here overrides the file’s value; the presentation fields are only ever set here.

Parameters:

data (Any)

Show JSON schema
{
   "title": "CitationModel",
   "description": "Model for an entry in the ``[[project.citations]]`` array of\ndocumenteer.toml.\n\nAn entry carries both the work's bibliographic fields and the\npresentation fields that say how the site displays it. The bibliographic\nfields can instead come from a CITATION.cff file, named by ``cff``, in\nwhich case a field set here overrides the file's value; the presentation\nfields are only ever set here.",
   "type": "object",
   "properties": {
      "doi": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The work's DOI, written bare (``10.NNNN/suffix``), as a https://doi.org/ URL, or with a ``doi:`` prefix. Required for the ``self`` entry; every other entry may instead be located by ``url``. A ``cff`` file can supply either.",
         "title": "Doi"
      },
      "url": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The work's landing page, which locates a work that has no DOI, as an absolute http or https URL. A ``cff`` file supplies one from its ``url``, or from its ``repository-code`` when it states no landing page.",
         "title": "Url"
      },
      "label": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A short label for this citation, shown as the heading of its card and in the site footer, such as \"Dataset\" or \"TAP\". It is a display string and need not be unique: a citation's identity is its bibtex_key, which the build keeps distinct across the site.",
         "title": "Label"
      },
      "type": {
         "anyOf": [
            {
               "$ref": "#/$defs/CitationType"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The kind of work being cited, which decides the schema.org type the site publishes it under. A cff file supplies one when this is unset."
      },
      "self": {
         "default": false,
         "description": "Whether this site is this DOI's registered landing page. At most one entry can set it. It says nothing about which citation the site asks readers to use, which is ``preferred``.",
         "title": "Self",
         "type": "boolean"
      },
      "preferred": {
         "default": false,
         "description": "Whether this is the citation the site asks readers to use. At most one entry can set it; it defaults to the ``self`` entry when the site has one.",
         "title": "Preferred",
         "type": "boolean"
      },
      "in_footer": {
         "anyOf": [
            {
               "type": "boolean"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Whether this citation appears in the site footer. Defaults to true for the preferred entry and for the ``self`` entry \u2014 the same entry unless the site separates them \u2014 and false for every other.",
         "title": "In Footer"
      },
      "note": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Free text about when to use this citation, displayed alongside it.",
         "title": "Note"
      },
      "page": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The page inside this site that is the DOI's registered landing page, as a Sphinx docname with an optional fragment (``products/catalogs/object#tap``). Unset means the site as a whole is the landing page.",
         "title": "Page"
      },
      "bibtex_key": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The key this citation's BibTeX entry is written under, such as ``RTN-115``. Defaults to the site's lsst.io subdomain for the entry describing this site's own work, to the DOI for any other entry that has one, and to author-year-title otherwise. Set it to pin a key a manuscript already cites.",
         "title": "Bibtex Key"
      },
      "title": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The title of the cited work.",
         "title": "Title"
      },
      "authors": {
         "description": "The work's authors, in the order they should be credited. Setting any author replaces the whole author list a ``cff`` file supplies.",
         "items": {
            "$ref": "#/$defs/CitationAuthorModel"
         },
         "title": "Authors",
         "type": "array"
      },
      "publisher": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The organization that published the work.",
         "title": "Publisher"
      },
      "version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The release of the work being cited, such as a package's 12.3.0. A ``cff`` file supplies one from its ``version``. A software entry that describes this site's own package \u2014 one that sets ``self``, ``preferred``, or ``cff_preferred = false`` \u2014 defaults to the project's own version when neither states one.",
         "title": "Version"
      },
      "date": {
         "anyOf": [
            {
               "$ref": "#/$defs/PartialDate"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The work's publication date, stated to the precision its source knows: a TOML date (2025-06-30), a bare year (2025), or a quoted ISO 8601 date (\"2025-06\" or \"2025\"). Only its year appears in a rendered citation."
      },
      "cff": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Path to a CITATION.cff file supplying the bibliographic fields, relative to documenteer.toml (typically ``../CITATION.cff``).",
         "title": "Cff"
      },
      "cff_preferred": {
         "default": true,
         "description": "Whether a preferred-citation in the ``cff`` file is the record read, as GitHub's \u201cCite this repository\u201d button does. Set it false to cite the file's top-level record \u2014 the software or dataset the repository itself is \u2014 instead.",
         "title": "Cff Preferred",
         "type": "boolean"
      }
   },
   "$defs": {
      "CitationAuthorModel": {
         "description": "Model for an author of a ``[[project.citations]]`` entry.\n\nAn author is either a person, named with ``family_name`` (and usually\n``given_name``), or an organization, named with ``name``. The split\nmatters to a rendered citation: a person's name is set family-name-first\nand may be abbreviated by a BibTeX style, where an organization's is\nprotected from both.",
         "properties": {
            "name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The organization's name, for an author that is an institution rather than a person.",
               "title": "Name"
            },
            "ror": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The organization's ROR (ror.org) identifier. Only meaningful alongside ``name``.",
               "title": "Ror"
            },
            "family_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The person's family name (last name in western culture).",
               "title": "Family Name"
            },
            "given_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The person's given name (first name in western culture).",
               "title": "Given Name"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The person's ORCID, as a URL or a bare identifier. Only meaningful alongside ``family_name``.",
               "title": "Orcid"
            },
            "affiliation": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The person's affiliation, as a single display name. Only meaningful alongside ``family_name``.",
               "title": "Affiliation"
            }
         },
         "title": "CitationAuthorModel",
         "type": "object"
      },
      "CitationType": {
         "description": "The kind of work a citation describes.\n\nThis is the citation's counterpart to DataCite's\n``resourceTypeGeneral``: it says what the cited thing *is*, which is what\ndecides the schema.org type a landing page publishes it under (see\n``SCHEMA_ORG_TYPES``). A work whose type is unstated is not forced into one\n\u2014 an untyped citation keeps the generic default \u2014 so the vocabulary can\nstay small and every member can mean something definite.",
         "enum": [
            "dataset",
            "article",
            "software",
            "report",
            "other"
         ],
         "title": "CitationType",
         "type": "string"
      },
      "PartialDate": {
         "description": "A publication date stated to the precision its source knows.\n\nA bibliographic source rarely states a full day. A ``.bib`` file, a\njournal's front matter, and a CITATION.cff reference commonly give a year\nalone, and DataCite's own mandatory metadata is a ``publicationYear``.\nCarrying such a date as a `datetime.date` would mean inventing a month and\na day \u2014 and since Documenteer publishes the date as schema.org\n``datePublished``, the invented day would then be asserted as fact on\nevery page of a site. ISO 8601 spells reduced precision as ``YYYY`` and\n``YYYY-MM``, schema.org ``Date`` is ISO 8601, and DataCite's crosswalk\nmaps ``publicationYear`` onto ``datePublished`` as a bare year; this type\nis that spelling.\n\nA rendered citation shows only the year at every precision, so stating a\ndate to the year costs a reader nothing: only the machine-readable\nmetadata tells the three precisions apart.",
         "properties": {
            "year": {
               "title": "Year",
               "type": "integer"
            },
            "month": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Month"
            },
            "day": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Day"
            }
         },
         "required": [
            "year"
         ],
         "title": "PartialDate",
         "type": "object"
      }
   }
}

Config:

  • populate_by_name: bool = True

  • validate_by_alias: bool = True

  • validate_by_name: bool = True

Fields:
Validators:
field authors: list[CitationAuthorModel] [Optional]#

The work’s authors, in the order they should be credited. Setting any author replaces the whole author list a cff file supplies.

Validated by:
field bibtex_key: str | None = None#

The key this citation’s BibTeX entry is written under, such as RTN-115. Defaults to the site’s lsst.io subdomain for the entry describing this site’s own work, to the DOI for any other entry that has one, and to author-year-title otherwise. Set it to pin a key a manuscript already cites.

Validated by:
field cff: str | None = None#

Path to a CITATION.cff file supplying the bibliographic fields, relative to documenteer.toml (typically ../CITATION.cff).

Validated by:
field cff_preferred: bool = True#

Whether a preferred-citation in the cff file is the record read, as GitHub’s “Cite this repository” button does. Set it false to cite the file’s top-level record — the software or dataset the repository itself is — instead.

Validated by:
field date: PartialDate | None = None#

The work’s publication date, stated to the precision its source knows: a TOML date (2025-06-30), a bare year (2025), or a quoted ISO 8601 date (“2025-06” or “2025”). Only its year appears in a rendered citation.

Validated by:
field doi: str | None = None#

The work’s DOI, written bare (10.NNNN/suffix), as a https://doi.org/ URL, or with a doi: prefix. Required for the self entry; every other entry may instead be located by url. A cff file can supply either.

Validated by:

Whether this citation appears in the site footer. Defaults to true for the preferred entry and for the self entry — the same entry unless the site separates them — and false for every other.

Validated by:
field is_preferred: bool = False (alias 'preferred')#

Whether this is the citation the site asks readers to use. At most one entry can set it; it defaults to the self entry when the site has one.

Validated by:
field is_self: bool = False (alias 'self')#

Whether this site is this DOI’s registered landing page. At most one entry can set it. It says nothing about which citation the site asks readers to use, which is preferred.

Validated by:
field label: str | None = None#

A short label for this citation, shown as the heading of its card and in the site footer, such as “Dataset” or “TAP”. It is a display string and need not be unique: a citation’s identity is its bibtex_key, which the build keeps distinct across the site.

Validated by:
field note: str | None = None#

Free text about when to use this citation, displayed alongside it.

Validated by:
field page: str | None = None#

The page inside this site that is the DOI’s registered landing page, as a Sphinx docname with an optional fragment (products/catalogs/object#tap). Unset means the site as a whole is the landing page.

Validated by:
field publisher: str | None = None#

The organization that published the work.

Validated by:
field title: str | None = None#

The title of the cited work.

Validated by:
field type: CitationType | None = None#

The kind of work being cited, which decides the schema.org type the site publishes it under. A cff file supplies one when this is unset.

Validated by:
field url: str | None = None#

The work’s landing page, which locates a work that has no DOI, as an absolute http or https URL. A cff file supplies one from its url, or from its repository-code when it states no landing page.

Validated by:
field version: str | None = None#

The release of the work being cited, such as a package’s 12.3.0. A cff file supplies one from its version. A software entry that describes this site’s own package — one that sets self, preferred, or cff_preferred = false — defaults to the project’s own version when neither states one.

Validated by:
validator validate_bibtex_key  »  bibtex_key#

Strip the citation key, rejecting one BibTeX cannot read.

The key is what a reader’s own bibliography cites the work by, so a key that would end early or mean something else to BibTeX is caught where it is written rather than composed into an entry that breaks the .bib file it is pasted into.

Parameters:

v (str | None)

Return type:

str | None

validator validate_date  »  date#

Read the publication date at the precision it is written in.

Parameters:

v (Any)

Return type:

PartialDate | None

validator validate_doi  »  doi#

Normalize the DOI to its bare form, rejecting a non-DOI.

Parameters:

v (str | None)

Return type:

str | None

validator validate_page  »  page#

Normalize the page claim to docname or docname#fragment.

A Sphinx docname carries neither a leading slash nor a file extension, so a leading slash — the spelling a reader borrows from a URL — is dropped rather than rejected.

Parameters:

v (str | None)

Return type:

str | None

validator validate_url  »  url#

Strip the landing-page URL, rejecting one that could not be linked.

The value is validated here, where it is written, rather than where a citation is composed, so that the entry-level check for a locatable work sees the same URL the site would render. A blank one is the case that motivates it: it is truthy, so it passes that check, and then composes to no link at all.

Parameters:

v (str | None)

Return type:

str | None

validator validate_version  »  version#

Read the release the entry names.

Parameters:

v (str | None)

Return type:

str | None

Whether the citation appears in the site footer, resolving the default from the entry’s two roles.

An entry defaults into the footer when it fills either role. The preferred citation is there because it is what the site asks readers to use. The self entry is there because the site is that DOI’s landing page, and DataCite asks a landing page to display the citation of the DOI it is the landing page of — which the footer is what makes true of every page of the site. The two are the same entry on a site that marks no other preferred, so only a site that separates them shows two footer citations by default, which is the honest rendering of a site that both is a landing page and asks readers to cite something else.

Parameters:

is_preferred (bool) – Whether this entry is the site’s preferred citation, as ProjectModel.preferred_citation resolves it. It is passed in rather than read from is_preferred because the default is inherited by the self entry of a site that marks no entry preferred, which an entry cannot see on its own.

Return type:

bool

validator validate_cff_preferred_needs_cff  »  all fields#

Reject an entry that chooses a record inside a CITATION.cff file without naming one.

cff_preferred says which of a file’s two records — the preferred citation or the top-level one — the entry reads, so an entry with no cff states a preference over nothing and would be read as having no effect. It is also the field most easily confused with preferred, which chooses the site’s headline citation, and an entry that meant that one is exactly the entry that writes this one alone.

Return type:

Self

validator validate_self_claims_no_page  »  all fields#

Reject an entry that claims both the site and a page inside it as the DOI’s landing page.

self and page answer the same question — where this DOI resolves — so an entry that sets both states two landing pages for one work, and the site would publish it at both. Asking readers to cite a work documented on a page of this site is a different claim, made with preferred, which does combine with page.

Return type:

Self

property page_docname: str | None#

The docname of the claimed page, without its fragment.

property page_fragment: str | None#

The fragment of the claimed page, without its leading #, or None when the whole page is claimed.

This page was last modified on .

https://documenteer.lsst.io/dev/api/contents/documenteer.conf._toml.CitationModel.html