Add OpenCitations

[koppor]

User description

This adds support for OpenCitations.

Steps to test

1. Open Chocolate.bib
2. Select any entry
3. Open tab "Citations"
4. Switch to "OpenCitations"

Mandatory checks

• I own the copyright of the code submitted and I license it under the MIT license
• 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 described the change in CHANGELOG.md in a way that is understandable for the average user (if change is visible to the user)
• [/] I checked the user documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request updating file(s) in https://github.com/JabRef/user-documentation/tree/main/en.

---

PR Type

Enhancement

---

Description

• Add OpenCitations fetcher support for citation relations

• Implement bidirectional binding for fetcher selection preference

• Create response model classes for OpenCitations API

• Fix DOI URL encoding in CrossRef fetcher

• Unify citation fetcher initialization in CLI commands

---

Diagram Walkthrough

flowchart LR
  A["CitationFetcherType"] -->|"adds OPEN_CITATIONS"| B["OpenCitationsFetcher"]
  B -->|"uses"| C["CitationItem<br/>CountResponse"]
  B -->|"fetches via"| D["OpenCitations API"]
  E["CitationRelationsTab"] -->|"bidirectional bind"| F["entryEditorPreferences"]
  E -->|"uses"| A
  G["CrossRef"] -->|"URL encode DOI"| H["API Request"]
  I["GetCitingWorks<br/>GetCitedWorks"] -->|"unified initialization"| A

Loading

File Walkthrough

	Relevant files
Enhancement	8 files OpenCitationsFetcher.java Implement OpenCitations citation fetcher core                        +160/-0  CitationItem.java Create CitationItem response model class                                  +59/-0    CountResponse.java Create CountResponse model for citation counts                      +20/-0    CitationFetcherType.java Register OpenCitations fetcher in enum                                      +6/-2      SemanticScholarCitationFetcher.java Update fetcher name and nullability annotations                    +6/-5      CitationRelationsTab.java Implement bidirectional preference binding for fetcher      +15/-13  GetCitedWorks.java Change default fetcher to OpenCitations                                    +9/-10    GetCitingWorks.java Add provider option and unify fetcher initialization          +28/-2
Bug fix	1 files CrossRef.java URL encode DOI identifiers in API requests                              +5/-3
Documentation	2 files CHANGELOG.md Document OpenCitations support and DOI encoding fix            +2/-0      references.md Clarify references definition and structure                            +2/-1

---

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

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🔴	URL injection vulnerability Description: The DOI value is directly concatenated into the API URL without proper URL encoding, which could lead to URL injection or malformed requests if the DOI contains special characters. OpenCitationsFetcher.java [50-50] Referred Code return API_BASE_URL + "/" + endpoint + "/doi:" + doi; }
⚪	API key exposure risk Description: The API key is added as a header value without validation or sanitization, potentially exposing sensitive credentials if the key contains unexpected characters or is logged. OpenCitationsFetcher.java [76-76] Referred Code .ifPresent(apiKey -> urlDownload.addHeader("authorization", apiKey));
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Silent error handling: The fetchBibEntryFromIdentifiers method catches FetcherException but only logs a warning without providing actionable context to the caller or handling the failure case appropriately. Referred Code } catch (FetcherException e) { LOGGER.warn("Could not fetch BibEntry for DOI: {}", doiIdentifier.get().value(), e); } Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Missing input validation: The getApiUrl method constructs API URLs using DOI values without validating or sanitizing the DOI string before concatenation, which could lead to URL injection if DOI contains malicious characters. Referred Code private String getApiUrl(String endpoint, BibEntry entry) throws FetcherException { String doi = entry.getDOI() .orElseThrow(() -> new FetcherException("Entry does not have a DOI")) .asString(); return API_BASE_URL + "/" + endpoint + "/doi:" + doi; } Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

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

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Use a generic DOI-based fetcher Replace the direct dependency on CrossRef fetcher in the new OpenCitationsFetcher with a more generic DoiFetcher. This will decouple the components and improve modularity. Examples: jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/opencitations/OpenCitationsFetcher.java [35] private final CrossRef crossRefFetcher = new CrossRef(); jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/opencitations/OpenCitationsFetcher.java [139] Optional<BibEntry> fetchedEntry = crossRefFetcher.performSearchById(doiIdentifier.get().value()); Solution Walkthrough: Before: // jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/opencitations/OpenCitationsFetcher.java public class OpenCitationsFetcher implements CitationFetcher { private final ImporterPreferences importerPreferences; private final CrossRef crossRefFetcher = new CrossRef(); public OpenCitationsFetcher(ImporterPreferences importerPreferences) { this.importerPreferences = importerPreferences; } private BibEntry fetchBibEntryFromIdentifiers(List<CitationItem.IdentifierWithField> identifiers) { // ... if (doiIdentifier.isPresent()) { Optional<BibEntry> fetchedEntry = crossRefFetcher.performSearchById(doiIdentifier.get().value()); // ... } // ... } } After: // jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/opencitations/OpenCitationsFetcher.java public class OpenCitationsFetcher implements CitationFetcher { private final ImporterPreferences importerPreferences; private final DoiFetcher doiFetcher; public OpenCitationsFetcher(ImporterPreferences importerPreferences) { this.importerPreferences = importerPreferences; this.doiFetcher = new DoiFetcher(importerPreferences); } private BibEntry fetchBibEntryFromIdentifiers(List<CitationItem.IdentifierWithField> identifiers) { // ... if (doiIdentifier.isPresent()) { Optional<BibEntry> fetchedEntry = doiFetcher.performSearchById(doiIdentifier.get().value()); // ... } // ... } } Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a tight coupling between the new OpenCitationsFetcher and CrossRef, and proposing to use the more generic DoiFetcher significantly improves modularity and robustness.	Medium
Possible issue	URL-encode DOI to prevent request errors URL-encode the DOI in getApiUrl to prevent malformed URLs and ensure correct API requests, consistent with other fixes in this PR. jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/opencitations/OpenCitationsFetcher.java [46-51] private String getApiUrl(String endpoint, BibEntry entry) throws FetcherException { String doi = entry.getDOI() .orElseThrow(() -> new FetcherException("Entry does not have a DOI")) .asString(); - return API_BASE_URL + "/" + endpoint + "/doi:" + doi; + return API_BASE_URL + "/" + endpoint + "/doi:" + URLEncoder.encode(doi, StandardCharsets.UTF_8); } Apply / Chat Suggestion importance[1-10]: 8 __ Why: This is a valid and important bug fix. The PR's changelog explicitly mentions fixing an issue with DOIs containing URL-invalid characters, and this suggestion correctly points out that the new OpenCitationsFetcher fails to apply the same fix, which could lead to runtime errors.	Medium
General	Avoid adding identifiers with empty values In extractIdentifiers, add a check to prevent creating identifiers with empty values, such as from a "doi: " string. jablib/src/main/java/org/jabref/logic/importer/fetcher/citation/opencitations/CitationItem.java [30-50] List<IdentifierWithField> extractIdentifiers(@Nullable String pidString) { if (pidString == null || pidString.isEmpty()) { return List.of(); } String[] pids = pidString.split("\\s+"); List<IdentifierWithField> identifiers = new ArrayList<>(); for (String pid : pids) { int colonIndex = pid.indexOf(':'); if (colonIndex > 0) { String prefix = pid.substring(0, colonIndex); String value = pid.substring(colonIndex + 1); - Field field = FieldFactory.parseField(prefix); - identifiers.add(new IdentifierWithField(field, value)); + if (!value.isEmpty()) { + Field field = FieldFactory.parseField(prefix); + identifiers.add(new IdentifierWithField(field, value)); + } } else { identifiers.add(new IdentifierWithField(StandardField.NOTE, pid)); } } return identifiers; } Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies a potential issue where an identifier with an empty value could be created. While this is a good defensive programming practice, its impact is minor as it's unlikely to receive such malformed data from the API.	Low
Learned best practice	✅ Complete incomplete documentation sentence Suggestion Impact: The commit addressed the incomplete sentence issue but chose a different solution. Instead of adding "or bibliography of a scholarly document" as suggested, the commit simply removed the trailing "or the" to make the sentence complete and grammatically correct. code diff: -It is usually described as the outgoing references to other cited works appearing in the reference list or the +It is usually described as the outgoing references to other cited works appearing in the reference list. The sentence appears incomplete and ends abruptly. Complete the sentence to clearly describe what references represent in the context of scholarly works. docs/glossary/references.md [13] -It is usually described as the outgoing references to other cited works appearing in the reference list or the +It is usually described as the outgoing references to other cited works appearing in the reference list or bibliography of a scholarly document. [Suggestion processed] Suggestion importance[1-10]: 5 __ Why: Relevant best practice - Fix typographical errors in documentation to maintain professionalism and clarity. Incomplete sentences or malformed text should be corrected.	Low
Update

[Siedlerchr]

why bidirectional?

[koppor]

1. Common pattern in JabRef's code base
2. It might be that some other UI element will allow for changing the citatoin fetcher. E.g., when checking citation counts at org.jabref.gui.fieldeditors.CitationCountEditor

[Siedlerchr]

is this class here really necessary?

[koppor]

DTO pattern. Better consistency in always using a DTO in this class than case-by-case

--> CitatonItem is the other DTO.

[calixtus]

Will you do this or for follow-up

[koppor]

Maybe me, maybe someone else. This was in before - I created an issue for this.