Change JSON format of BibTeX and add ADR on JSON format

[koppor]

We need to have an ADR describing the JSON format used to exchange BibTeX data via HTTP. Refs #67.

After digging more into alternatives for the JSON format, I ask to change our things send/received from/to the server. We seprated meta and content similar as https://github.com/ORCID/bibtexParseJs does.

Seeing https://github.com/chbrown/tex/blob/master/tests/bibfiles/W11-1107.json, I think, the ORCID-Approach is over-engineered and we should go with a plain key-value map.

Options:

• ORCID-Approach
• Example:

   { 
      "citationKey": "examplekey1",
      "entryType": "article",
      "entryTags": { 
        "title": "example title"
      }
   }

• https://github.com/chbrown/tex

  • Example:

    {
      "pubtype": "InProceedings",
      "citekey": null,
      "author": "Pradeep Muthukrishnan and Dragomir Radev and Qiaozhu Mei",
      "title": "Simultaneous Similarity Learning and Feature-Weight Learning for Document Clustering",
      "booktitle": "Proceedings of TextGraphs-6: Graph-based Methods for Natural Language Processing",
      "month": "June",
      "year": "2011",
      "address": "Portland, Oregon",
      "publisher": "Association for Computational Linguistics",
      "url": "http://www.aclweb.org/anthology/W11-1107",
      "pages": "42--50"
    }

  • Bad, because it mixes up meta data (type and key) with real data: https://github.com/chbrown/tex/blob/master/tests/bibfiles/W11-1107.json. (conflicts in pubtype and citekey could occur in some cases)

  • Good, because citekey is also used by BibLaTeX

    You may also use the ‘citekey’ or ‘entrykey‘ pseudo-fields to specify the citation/entry key as part of the label

• https://www.npmjs.com/package/bibtex-parse-js - similar to current approach, maintained by ORCID
  • Good, because maintained by ORCID
  • Bad, because not really maintained Fix parsing of a key-like value at end of entry ORCID/bibtexParseJs#28 is not merged since months
• https://www.npmjs.com/package/@hygull/bibtex - good json, has code quality issues with capitalization of BibTeX (Updated require statement hygull/bibtex#3 (review))
• https://github.com/digitalheir/bibtex-js - unclear how JSON looks like
• bib2json - not a large community
  • https://www.npmjs.com/package/metalsmith-bibtex relies on it
• https://github.com/mikolalysenko/bibtex-parser - not sure how JSON looks like; small community, no updates since 7 years
• citation-js-plugin-bibtex. Too fine grained - see https://github.com/citation-js/citation-js/blob/master/packages/plugin-bibtex/test/input.json for an example
• CLS-JSON - neglegeted because the author field needs to be refined - and we want to have a simple conversion
• https://github.com/tamuratak/latex-utensils seems to be too low level
• https://github.com/Aerijo/tree-sitter-bibtex/tree/master/src/tree_sitter - not maintained, no examples in repo to check JSON format

(Maybe investigate more at https://www.npmjs.com/search?q=keywords:bibtex)

Library to read bibtex directly

• https://www.npmjs.com/package/@retorquere/bibtex-parser --> https://github.com/retorquere/bibtex-parser

[koppor]

To make it clear: plain-key-value-map:

{
  "entrytype": "InProceedings",
  "citekey": "exampleKey",
  "author": "Pradeep Muthukrishnan and Dragomir Radev and Qiaozhu Mei",
  "title": "Simultaneous Similarity Learning and Feature-Weight Learning for Document Clustering",
  "booktitle": "Proceedings of TextGraphs-6: Graph-based Methods for Natural Language Processing",
  "month": "June",
  "year": "2011",
  "address": "Portland, Oregon",
  "publisher": "Association for Computational Linguistics",
  "url": "http://www.aclweb.org/anthology/W11-1107",
  "pages": "42--50"
}

The EntryType goes into entrytype and CiteKey ("Citation Key") goes into citekey. (In the options in the issue desription, it was pubtype, but entrytype is more consistent to JabRef's model, isn't it?)