path: root/guide/src/entity_fields.md

# Entity Field Reference

All entities have:

- `extra`: free-form JSON metadata

The "extra" field is an "escape hatch" to include extra fields not in the
regular schema. It is intented to enable gradual evolution of the schema, as
well as accomodating niche or field-specific content. That being said,
reasonable limits should be adhered to.

## Containers

- `name`: (string, required). The title of the publication, as used in
  international indexing services. Eg, "Journal of Important Results". Not
  necessarily in the native language, but also not necessarily in English.
  Alternative titles (and translations) can be stored in "extra" metadata
  (TODO: what field?).
- `publisher` (string): The name of the publishing organization. Eg, "Society
  of Curious Students".
- `issnl` (string): an external identifier, with registration controlled by the
  [ISSN organization](http://www.issn.org/). Registration is relatively
  inexpensive and easy to obtain (depending on world region), so almost all
  serial publications have one. The ISSN-L ("linking ISSN") is one of either
  the print ("ISSNp") or electronic ("ISSNe") identifiers for a serial
  publication; not all publications have both types of ISSN, but many do, which
  can cause confusion. The ISSN master list is not gratis/public, but the
  ISSN-L mapping is.
- `wikidata_qid` (string): external linking identifier to a Wikidata entity.
- `abbrev` (string): a commonly used abbreviation for the publication, as used
  in citations, following the [ISO 4]() standard. Eg, "Journal of Polymer
  Science Part A" -> "J. Polym. Sci. A". Alternative abbreviations can be
  stored in "extra" metadata. (TODO: what field?)
- `coden` (string): an external identifier, the [CODEN code](). 6 characters,
  all upper-case.

[CODEN]: https://en.wikipedia.org/wiki/CODEN

## Creators

See ["Human Names"](./style_guide.index##human-names) sub-section of style
guide.

- `display_name` (string, required): Eg, "Grace Hopper".
- `given_name` (string): Eg, "Grace".
- `surname` (string): Eg, "Hooper".
- `orcid` (string): external identifier, as registered with ORCID.
- `wikidata_qid` (string): external linking identifier to a Wikidata entity.

## Files

- `size` (positive, non-zero integer): Eg: 1048576.
- `sha1` (string): Eg: "f013d66c7f6817d08b7eb2a93e6d0440c1f3e7f8".
- `md5`: Eg: "d41efcc592d1e40ac13905377399eb9b".
- `sha256`: Eg: "a77e4c11a57f1d757fca5754a8f83b5d4ece49a2d28596889127c1a2f3f28832".
- `urls`: An array of "typed" URLs. Order is not meaningful, and may not be
  preserved.
    - `url` (string, required):
            Eg: "https://example.edu/~frau/prcding.pdf".
    - `rel` (string, required):
            Eg: "webarchive".
- `mimetype` (string):
    example: "application/pdf"
- `releases` (array of identifiers): references to `release` entities that this
  file represents a manifestation of. Note that a single file can contain
  multiple release references (eg, a PDF containing a full issue with many
  articles), and that a release will often have multiple files (differing only
  by watermarks, or different digitizations of the same printed work, or
  variant MIME/media types of the same published work). See also
  "Work/Release/File Distinctions".

## Releases

- `title: (required)
        type: string
- `work_id:
        type: string
        example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- `container:
        $ref: "#/definitions/container_entity"
        description: "Optional; GET-only"
- `files:
        description: "Optional; GET-only"
        type: array
        items:
          $ref: "#/definitions/file_entity"
- `container_id:
        type: string
        example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- `release_type:
        type: string
        example: "book"
- `release_status:
        type: string
        example: "preprint"
- `release_date:
        type: string
        format: date
- `doi:
        type: string
        #format: custom
        example: "10.1234/abcde.789" See the "External Identifiers" section of style guide.
- `isbn13` (string): external identifer for books. ISBN-9 and other formats
  should be converted to canonical ISBN-13. See the "External Identifiers"
  section of style guide.
- `core_id` (string): external identifier for the [CORE] open access
  aggregator. These identifiers are integers, but stored in string format. See
  the "External Identifiers" section of style guide.
- `pmid` (string): external identifier for PubMed database. These are bare
  integers, but stored in a string format. See the "External Identifiers"
  section of style guide.
- `pmcid` (string): external identifier for PubMed Central database. These are
  integers prefixed with "PMC" (upper case), like "PMC4321". See the "External
  Identifiers" section of style guide.
- `wikidata_qid` (string): external identifier for Wikidata entities. These are
  integers prefixed with "Q", like "Q4321". Each `release` entity can be
  associated with at most one Wikidata entity (this field is not an array), and
  Wikidata entities should be associated with at most a single `release`. In
  the future it may be possible to associate Wikidata entities with `work`
  entities instead. See the "External Identifiers" section of style guide.
- `volume` (string): optionally, stores the specific volume of a serial
  publication this release was published in.
        type: string
- `issue` (string): optionally, stores the specific issue of a serial
  publication this release was published in.
- `pages` (string): the pages (within a volume/issue of a publication) that
  this release can be looked up under. This is a free-form string, and could
  represent the first page, a range of pages, or even prefix pages (like
  "xii-xxx").
- `publisher` (string): name of the publishing entity. This does not need to be
  populated if the associated `container` entity has the publisher field set,
  though it is acceptable to duplicate, as the publishing entity of a container
  may differ over time. Should be set for singleton releases, like books.
- `language` (string): the primary language used in this particular release of
  the work. Only a single language can be specified; additional languages can
  be stored in "extra" metadata (TODO: which field?). This field should be a
  valid RFC1766/ISO639-1 language code ("with extensions"), aka a controlled
  vocabulary, not a free-form name of the language.
- `contribs`: an array of authorship and other `creator` contributions to this
  release. Contribution fields include:
    - `index` (integer, optional): the (zero-indexed) order of this
      author. Authorship order has significance in many fields. Non-author
      contributions (illustration, translation, editorship) may or may not be
      ordered, depending on context, but index numbers should be unique per
      release (aka, there should not be "first author" and "first translator")
    - `creator_id` (identifier): if known, a reference to a specific `creator`
    - `raw_name` (string): the name of the contributor, as attributed in the
      text of this work. If the `creator_id` is linked, this may be different
      from the `display_name`; if a creator is not linked, this field is
      particularly important. Syntax and name order is not specified, but most
      often will be "display order", not index/alphabetical (in Western
      tradition, surname followed by given name).
    - `role` (string, of a set): the type of contribution, from a controlled
      vocabulary. TODO: vocabulary needs review.
    - `extra` (string): additional context can go here. For example, author
      affiliation, "this is the corresponding author", etc.
- `refs`: an array of references (aka, citations) to other releases. References
  can only be linked to a specific target release (not a work), though it may
  be ambugious which release of a work is being referenced if the citation is
  not specific enough. Reference fields include:
    - index:
        type: integer
        format: int64
    - target_release_id:
        type: string
        #format: ident
    - extra:
        type: object
        additionalProperties: {}
    - key:
        type: string
    - year:
        type: integer
        format: int64
    - container_title:
        type: string
    - title:
        type: string
    - locator:
        type: string
        example: "p123"

Controlled vocabulary for `release_type` is derived from the Crossref `type`
vocabulary:

- `journal-article`
- `proceedings-article`
- `monograph`
- `dissertation`
- `book` (and `edited-book`, `reference-book`)
- `book-chapter` (and `book-part`, `book-section`, though much rarer) is
  allowed as these are frequently referenced and read independent of the entire
  book. The data model does not currently support linking a subset of a release
  to an entity representing the entire release. The release/work/file
  distinctions should not be used to group chapters into complete work; a book
  chapter can be it's own work. A paper which is republished as a chapter (eg,
  in a collection, or "edited" book) can have both releases under one work. The
  criteria of whether to "split" a book and have release entities for each
  chapter is whether the chapter has been cited/reference as such.
- `dissertation`
- `dataset` (though representation with `file` entities is TBD).
- `monograph`
- `report`
- `standard`
- `posted-content` is allowed, but may be re-categorized. For crossref, this
  seems to imply a journal article or report which is not published (pre-print)
- `other` matches Crossref `other` works, which may (and generally should) have
  a more specific type set.
- `web-post` (custom extension) for blog posts, essays, and other individual
  works on websites
- `website` (custom extension) for entire web sites and wikis.
- `presentation` (custom extension) for, eg, slides and recorded conference
  presentations themselves, as distinct from `proceedings-article`
- `editorial` (custom extension) for columns, "in this issue", and other
  content published along peer-reviewed content in journals. Can bleed in to
  "other" or "stub"
- `book-review` (custom extension)
- `letter` for "letters to the editor", "authors respond", and
  sub-article-length published content
- `example` (custom extension) for dummy or example releases that have valid
  (registered) identifiers. Other metadata does not need to match "canonical"
  examples.
- `stub` (custom extension) for releases which have notable external
  identifiers, and thus are included "for completeness", but don't seem to
  represent a "full work". An example might be a paper that gets an extra DOI
  by accident; the primary DOI should be a full release, and the accidental DOI
  can be a `stub` release under the same work. `stub` releases shouldn't be
  considered full releases when counting or aggregating (though if technically
  difficult this may not always be implemented). Other things that can be
  categorized as stubs (which seem to often end up miscategorized as full
  articles in bibliographic databases):
    - an abstract, which is only an abstract of a larger work
    - commercial advertisements
    - "trap" or "honey pot" works, which are fakes included in databases to
      detect re-publishing without attribution
    - "This page is intentionally blank"
    - "About the author", "About the editors", "About the cover"
    - "Acknowledgements"
    - "Notices"

Other types from Crossref (such as `component`, `reference-entry`) are valid,
but are not actively solicited for inclusion, as they are not the current focus
of the database.

In the future, some types (like `journal`, `proceedings`, and `book-series`)
will probably be represented as `container` entities. How to represent other
container-like types (like `report-series` or `book-series`) is TBD.

Controlled vocabulary for `release_status`:
- `published` for any version of the work that was "formally published", or any
  variant that can be considered a "proof", "camera ready", "archival",
  "version of record" or "definitive" that have no meaningful differences from
  the "published" version. Note that "meaningful" here will need to be
  explored.
- `corrected` for a version of a work that, after formal publication, has been
  revised and updated. Could be the "version of record".
- `pre-print`, for versions of a work which have not been submitted for peer
  review or formal publication
- `post-print`, often a post-peer-review version of a work that does not have
  publisher-supplied copy-editing, typesetting, etc.
- `draft` in the context of book publication or online content (shouldn't be
  applied to journal articles), is an unpublished, but somehow notable version
  of a work.
- If blank, indicates status isn't known, and wasn't inferred at creation time.
  Can often be interpreted as `published`.

Controlled vocabulary for `role` field on `contribs`:
- `author`
- `translator`
- `illustrator`
- `editor`
- If blank, indicates that type of contribution is not known; this can often be
  interpreted as authorship.

Current "extra" fields, flags, and content:
- `crossref` (object), for extra crossref-specific metadata
- `is_retracted` (boolean flag) if this work has been retracted
- `translation_of` (release identifier) if this release is a translation of
  another (usually under the same work)
- `arxiv_id` (string) external identifier to a (version-specific) [arxiv.org]()
  work

[arxiv.org]: https://arxiv.org

abstracts:
        type: array
        items:
          type: object
          properties:
            sha1:
              type: string
              example: "3f242a192acc258bdfdb151943419437f440c313"
            content:
              type: string
              example: "<jats:p>Some abstract thing goes here</jats:p>"
            mimetype:
              type: string
              example: "application/xml+jats"
            lang:
              type: string
              example: "en"
## Works