CitationDefaultsModel

pydantic model documenteer.conf._toml.CitationDefaultsModel

Model for the [project.citation_defaults] table of documenteer.toml.

A site that mints a DOI per data product declares dozens of [[project.citations]] entries that agree about almost everything: the same publisher, the same one-element author list, the same year, the same type. This table states each of those once, and every entry that leaves the field unstated takes it, so an entry is written as the handful of fields that tell one work from another.

Only the bibliographic fields are accepted, and only the ones a site’s works can genuinely share. Identity and presentation are per work — a DOI, a URL, a title, a label, a page, a note, a BibTeX key, the self and preferred claims, and the CITATION.cff file one entry reads each name a single work — so a default for any of them would be a value no entry could use. Writing one is a configuration error rather than a silently ignored key, which is also what catches a misspelling of a key the table does accept.

Parameters:

data (Any)

Show JSON schema

{
   "title": "CitationDefaultsModel",
   "description": "Model for the ``[project.citation_defaults]`` table of\ndocumenteer.toml.\n\nA site that mints a DOI per data product declares dozens of\n``[[project.citations]]`` entries that agree about almost everything: the\nsame publisher, the same one-element author list, the same year, the same\ntype. This table states each of those once, and every entry that leaves\nthe field unstated takes it, so an entry is written as the handful of\nfields that tell one work from another.\n\nOnly the *bibliographic* fields are accepted, and only the ones a site's\nworks can genuinely share. Identity and presentation are per work \u2014 a\nDOI, a URL, a title, a label, a page, a note, a BibTeX key, the ``self``\nand ``preferred`` claims, and the CITATION.cff file one entry reads each\nname a single work \u2014 so a default for any of them would be a value no\nentry could use. Writing one is a configuration error rather than a\nsilently ignored key, which is also what catches a misspelling of a key\nthe table does accept.",
   "type": "object",
   "properties": {
      "type": {
         "anyOf": [
            {
               "$ref": "#/$defs/CitationType"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The kind of work each entry that states no ``type`` is."
      },
      "publisher": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The organization that published each entry that names no ``publisher``.",
         "title": "Publisher"
      },
      "date": {
         "anyOf": [
            {
               "$ref": "#/$defs/PartialDate"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The publication date of each entry that states no ``date``, written in any of the forms an entry's own ``date`` accepts."
      },
      "authors": {
         "description": "The authors of each entry that names none. An entry that names any author replaces this list rather than adding to it.",
         "items": {
            "$ref": "#/$defs/CitationAuthorModel"
         },
         "title": "Authors",
         "type": "array"
      },
      "version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The release each entry that names no ``version`` is cited at, such as a data release's ``DP2.1``.",
         "title": "Version"
      }
   },
   "$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"
      }
   },
   "additionalProperties": false
}

Config:

• extra: str = forbid

Fields:

• authors (list[documenteer.conf._toml.CitationAuthorModel])

• date (documenteer.citations.PartialDate | None)

• publisher (str | None)

• type (documenteer.citations.CitationType | None)

• version (str | None)

Validators:

• validate_date » date

• validate_version » version

field authors: list[CitationAuthorModel] [Optional]

The authors of each entry that names none. An entry that names any author replaces this list rather than adding to it.

field date: PartialDate | None = None

The publication date of each entry that states no date, written in any of the forms an entry’s own date accepts.

Validated by:

• validate_date

field publisher: str | None = None

The organization that published each entry that names no publisher.

field type: CitationType | None = None

The kind of work each entry that states no type is.

field version: str | None = None

The release each entry that names no version is cited at, such as a data release’s DP2.1.

Validated by:

• validate_version

validator validate_date  »  date

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

Parameters:

v (Any)

Return type:

PartialDate | None

validator validate_version  »  version

Read the release the table names.

Parameters:

v (str | None)

Return type:

str | None