Change Reference fields to be closer to BibTeX

[mdoering]

We allow 3 different levels of parsed out references to be shared. A single citation string, a CSV reference "table" and BibTeX or CSL-JSON as the most structured formats. The CSV reference table contains just 7 fields, lumping various properties into details and missing editor, publisher and others. We should consider to drop harmonize that CSV table with BibTeX and CSL-JSON so that the most common fields are covered.

That could be:

• id: identifier for the reference
• type: the BibTeX Entry type, ie. article, book, inbook or misc
• doi: DOI for the reference. Can be in addition to another identifier used as the ID above
• author: The names of the author(s) as a list of Person objects with familyName & givenName (this deviates from BibTEX, see above for a Person)
• editor: The names of the editor(s) as a list of Person objects
• title: The title of the work
• booktitle: The title of the book, if only part of it is being cited
• journal: The journal or magazine the work was published in
• year: The year of publication (or, if unpublished, the year of creation)
• month: The month of publication (or, if unpublished, the month of creation) using integers from 1-12
• series: The series of books the book was published in
• volume: The volume of a journal or multi-volume book
• number: The "(issue) number" of a journal or magazine if applicable. Note that this is not the "article number" assigned by some journals`.
• edition: The edition of a book, long form (such as "First" or "Second")
• chapter: The chapter number
• pages: Page numbers, separated either by commas or double-hyphens.
• publisher: The publisher's name
• address: Publisher's address (usually just the city, but can be the full address for lesser-known publishers)
• version: dataset version
• ISBN: ISBN number (books)
• ISSN: ISSN serial number
• url: link to webpage for electronic resources
• note: e.g. Accessed Dec. 10, 2012

It would then also be the same as we use for citations inside the metadata.yaml

[mdoering]

Now that we have extracted the core CSL-JSON fields and use them also for source citations in metadata.yaml it makes most sense to also use these fields for the Reference.csv:

• id: identifier for the source, can be referenced from individual data records via sourceID to indicate the provenance on a record level.
• type: CSL type, e.g. ARTICLE-JOURNAL, BOOK, CHAPTER, DATASET, WEBPAGE. See https://aurimasv.github.io/z2csl/typeMap.xml for a mapping of CSL types to field sets
• doi: a DOI
• author: [name] author list
• editor: [name] editor list
• title: primary title of the item
• containerAuthor: [name] author of the container holding the item (e.g. the book author for a book chapter)
• containerTitle: title of the container holding the item (e.g. the book title for a book chapter, the journal title for a journal article)
• issued: [date] date the item was issued/published
• accessed: [date] date the item has been accessed
• collectionTitle: title of the collection holding the item (e.g. the series title for a book)
• collectionEditor: [name] editor of the collection holding the item (e.g. the series editor for a book)
• volume: [number] (container) volume holding the item (e.g. “2” when citing a chapter from book volume 2)
• issue: [number] (container) issue holding the item (e.g. “5” when citing a journal article from journal volume 2, issue 5)
• edition: [number] (container) edition holding the item (e.g. “3” when citing a chapter in the third edition of a book)
• page: range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue)
• publisher: publisher
• publisherPlace: geographic location of the publisher
• version: version of the item (e.g. “2.0.9” for a software program)
• isbn: International Standard Book Number
• issn: International Standard Serial Number
• url: link to webpage for electronic resources
• note/remarks: (short) inline note giving additional item details (e.g. a concise summary or commentary)

This is close to BibTeX, but as we use CSL-JSON primarily the terminology aligns better with our API. Compared to the initial model the changes are:

Unchanged

These fields still exist with the same meaning as before:

• doi
• author
• title
• remarks

Renamed

The following fields have a different name, but can silently be mapped to the new format to not break existing data:

• year -> issued
• source -> containerTitle
• link -> url

Problematic

• details: this field is an artificial lumping field to hold pages, volume, issue, chapters and other "details" for a reference. This is probably not used much and as ChecklistBank has to transform this into CSL somehow it mostly did this wrong so far.

Additions

Everything else are additions that do not break existing data, e.g. editors, publisher, ...

[mdoering]

I think even though the change is considerably, because we can still support backwards compatability it is a change to the better that should be included in the Version 1 release.

[mdoering]

@gdower I have now added this to the first official release and updated the readme, schema images and reference example data.