ADR for entry type and item type mapping selection

[pluto-han]

Related issues and pull requests

Related to #15875

PR Description

Add ADR for entry type and item type mapping selection

AI usage

Codex-5.4

---

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
• [/] I manually tested my changes in running JabRef (always required)
• [/] I added JUnit tests for changes (if applicable)
• [/] I added screenshots in the PR description (if change is visible to the user)
• [/] I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
• [/] I described the change in CHANGELOG.md in a way that can be understood by the average user (if change is visible to the user)
• [/] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add ADR 0061 for entry type and item type mapping selection

📝 Documentation

Walkthroughs

Description

• Adds ADR 0061 documenting entry type and item type mapping selection
• Evaluates four mapping strategies for Zotero compatibility
• Selects Better BibTeX mapping as primary solution
• Documents decision drivers, consequences, and trade-offs

Diagram

flowchart LR
  A["Zotero Compatibility Need"] --> B["Evaluate Mapping Strategies"]
  B --> C["citeproc-java"]
  B --> D["JabRef Natural Mapping"]
  B --> E["Zotero Natural Mapping"]
  B --> F["Better BibTeX Mapping"]
  F --> G["Selected Solution"]
  G --> H["Bidirectional Conversion Support"]

Loading

File Changes

1. docs/decisions/0061-EntryType-ItemType-mapping-selection.md 📝 Documentation +84/-0

ADR for entry type and item type mapping selection

• New ADR document establishing entry type to item type mapping strategy
• Defines context for Zotero compatibility implementation
• Evaluates four mapping options with pros and cons analysis
• Selects Better BibTeX mapping with fallback to JabRef/Zotero natural mappings

docs/decisions/0061-EntryType-ItemType-mapping-selection.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Trailing whitespace breaks markdownlint ✓ Resolved 🐞 Bug ☼ Reliability

Description

The new ADR has trailing spaces at the end of multiple lines, which violates markdownlint MD009 and
will fail the Markdown CI job. This blocks merging until the whitespace is removed.

Code

docs/decisions/0061-EntryType-ItemType-mapping-selection.md[R55-62]

+JabRef's internal behavior to map item type to entry type 
+
+* Good, because the mapping follows JabRef's internal behavior.
+* Good, because no new dependency is needed.
+* Bad, because we have limited control on the mapping
+* Bad, because it converts multiple item type to `misc`, which loses much information.
+
+### Use Zotero's natural mapping 

Evidence

The ADR contains lines with visible trailing whitespace, and CI runs markdownlint over documentation
without disabling the trailing-whitespace rule, so the build will fail until whitespace is removed.

docs/decisions/0061-EntryType-ItemType-mapping-selection.md[55-62]
.github/workflows/tests-code.yml[152-167]
.markdownlint.yml[1-8]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR contains trailing whitespace at the end of lines (e.g., after `entry type` and after a heading). This triggers markdownlint (MD009) in CI.
### Issue Context
CI runs `markdownlint-cli2-action` over `docs/**/*.md`, and the repo markdownlint config does not disable MD009.
### Fix Focus Areas
- docs/decisions/0061-EntryType-ItemType-mapping-selection.md[55-62]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Converter link path inconsistent ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The ADR’s citeproc-java converter URL uses a path segment citeproc/BibTeX/, which is inconsistent
with the converter package JabRef uses (de.undercouch.citeproc.bibtex.BibTeXConverter). This makes
the reference error-prone and may cause the documentation link checker to report a broken link.

Code

docs/decisions/0061-EntryType-ItemType-mapping-selection.md[44]

+Converter can be found via [this link](https://github.com/michel-kraemer/citeproc-java/blob/09d31a49090e06e6ab062016012b593897b3cb26/citeproc-java/src/main/java/de/undercouch/citeproc/BibTeX/BibTeXConverter.java#L420-L462)

Evidence

JabRef’s code imports the converter from the ...citeproc.bibtex... package, while the ADR points
to a different-cased/different-named directory (BibTeX) in the URL. Since CI runs linkspector on
docs, incorrect external URLs are surfaced as PR failures.

docs/decisions/0061-EntryType-ItemType-mapping-selection.md[42-45]
jablib/src/main/java/org/jabref/logic/citationstyle/JabRefItemDataProvider.java[25-28]
.github/workflows/check-links.yml[1-36]
.linkspector.yml[1-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The ADR links to `.../de/undercouch/citeproc/BibTeX/BibTeXConverter.java`, but JabRef imports `de.undercouch.citeproc.bibtex.BibTeXConverter`. The URL path should be updated to match the expected `bibtex` directory naming to avoid incorrect references and link-check failures.
### Issue Context
The repository runs a dedicated link checker (linkspector) on `docs/**/*.md`.
### Fix Focus Areas
- docs/decisions/0061-EntryType-ItemType-mapping-selection.md[44-44]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[subhramit]

all entry types of? Jabref?

[pluto-han]

all entry types of? Jabref?

Yes. Updated.

[koppor]

Good start.

I miss examples and where JabRef's current mapping is used.

[pluto-han]

Reply to #15907 (comment) and #15907 (comment):

The original JabRef's natural BibTeX/BibLaTeX mapping and Zotero's natural mapping are actually Zotero's internal export and import mapping.
Zotero's exporter for BibLaTeX
Zotero's exporter and importer for BibTeX

After the discussion with @subhramit, I modified the options. Please correct me if I misunderstand or miss something @subhramit @koppor .

[pluto-han]

Add citation-js as an option

[koppor]

Please also rename the file.

[pluto-han]

updated

[koppor]

I would have expected this ADR even more self-contained.

One example where mappings are different. In the DevCall you named an examle. Why not repeating it here?

[pluto-han]

example added

[subhramit]

Please add this in a follow up:

Suggested change

	We are implementing compatibility with Zotero. Zotero uses its item types, while JabRef uses BibTeX/BibLaTeX entry types. We need a suitable mapping strategy that preserves as much information as possible in both directions, from JabRef to Zotero and from Zotero to JabRef.
	We are implementing compatibility with Zotero. Zotero uses its [item types](https://www.zotero.org/support/kb/item_types_and_fields), while JabRef uses BibTeX/BibLaTeX entry types. We need a suitable mapping strategy that preserves as much information as possible in both directions, from JabRef to Zotero and from Zotero to JabRef.