Structured Citations

[GaziYucel]

Overview

The structured citations feature in OJS is designed to streamline the process of managing references within submissions. It allows authors and editors to input, process, and manage citations efficiently, ensuring accurate metadata retrieval and integration.

Acceptance criteria and detailed design specifications

User Path 1: Enable Structured Citations Setting at the Journal Level

• A toggle is available under Settings > Workflow > Submission > Metadata to enable or disable Structured Citations by default.
• However, this setting is not mandatory—editors can override it for individual submissions by going to the Publication > References tab and adjusting the setting there

User Path 2: Structured Citations during Article Submission Process

• When a new submission is started by the author or editor but has not yet been submitted, the References field will appear as a simple text input with no structured citations.
• Once the submission is officially submitted to the journal, the Structured Citations feature becomes available in the Publication tab and can be accessed from all workflow stages.

User Path 3: Author or Editor Adds Citations During Workflow

Submission > References Tab

• A dedicated References section allows authors (or editors) to input references as free-text, with each reference entered on a new line.

• A brief instruction appears above the field:

“Enter each reference on a new line. You can paste one or multiple references at a time. Click ‘Add’ to process them into structured citations.”

"Add" Button Behavior

• Clicking Add triggers metadata lookup via external services (e.g., Crossref) and attempts to match the reference with available DOI and citation metadata.
• While processing, a status message appears:

“Processing references… 0 of 4 added so far. This may take a few moments. You can continue working while the references are being retrieved.”

• A caution is also displayed:

“Some references may not return metadata. You can edit them manually once they’re added to the list.”

User Path 4: Display of Processed References in Structured Format

• Once processed, structured references appear in a tabular list below the text box.
• A success message is displayed:

“All references successfully added. You can review, edit, or remove them at any time.”

Table Actions

Each reference row includes:

• Formatted citation (retrieved or entered manually)
• DOI (if matched)
• Action buttons: Edit | Delete
• Clicking on "Edit" will open a modal where the user can fill more information about the citations or modify the existing one to make it structured

If users paste new references into the textbox and click Add again:

• The system detects and adds only unique entries.
• Duplicate references are ignored.

User Path 5: Deleting References

• A "Delete All Structured Citations" button appears above the table when entries exist.
• Clicking it opens a confirmation modal with the following message:

“Are you sure you want to delete all structured citations? This will remove all references currently listed. You’ll need to re-enter and process your references again if you continue.”

• Options: Cancel | Delete All

📽 Video Walkthrough:

https://youtu.be/KYPBl66oxQc
Figma Prototype - https://www.figma.com/proto/Wf7sDlUg2372jaKKTJ0Mgz/OJS-3.4-3.5?page-id=7200%3A7069&node-id=13467-15870&viewport=1476%2C-596%2C0.16&t=QyYooCIJnrzZccgk-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=13467%3A15870
Figma Design Link - https://www.figma.com/design/Wf7sDlUg2372jaKKTJ0Mgz/OJS-3.4-3.5?node-id=8934-12758&t=mSiC57aKAv6sL8eW-4

Additional Information from Backend Perspective

Add structured citations feature to OJS 3.5 and above.

Focus will be structuring references which are input in the free input field on the References section in the backend UI. The location of the structured citations will be under the current References text area field.

• database
  • citations: citation_id, publication_id, raw_citation, seq
  • citation_settings: citation_setting_id, citation_id, locale, setting_name, setting_value
  • authors and other fields in the schema are an array of objects, these will be saved as a json blob in citation_settings table
  • publication: useStructuredCitations
• UI Library components will be used
• the location in the UI will be under the References text area.
• adding references will still be done by adding in the References textarea as done now
• saving references will add a job to:
  • extract pids
  • retrieve structured meta data from external services
• all citations with an doi will be processed automatically:
  • extract doi
  • if doi found: structured citations will be retrieved from openalex
  • if doi not found, retrieve from crossref api:
    • match with score, title, family names authors
• when publication is published, a job will be added to deposit the citations to Open Citations repository
• include citations in exports
• citations will not be multi-lingual in this version

Pull requests
Part 1: Prepare DB for structured citations to come #11238

• pkp/pkp-lib#11238 prepare DB for structured citations #11239
• pkp/pkp-lib#11238 prepare DB for structured citations ojs#4819
• pkp/pkp-lib#11238 prepare DB for structured citations omp#1947
• pkp/pkp-lib#11238 prepare DB for structured citations ops#948

Part 2: structured citations

• structured citations #11270
• structured citations ui-library#600
• structured citations ojs#4839
• structured citations omp#1959
• structured citations ops#961
• structured citations crossrefReferenceLinking#32
• structured citations googleScholar#30
• structured citations jatsTemplate#87

Part 3: open citations

• ..

Repository branches

• https://github.com/GaziYucel/ojs/commits/I10692-structured-citations/
• https://github.com/GaziYucel/omp/tree/I10692-structured-citations
• https://github.com/GaziYucel/ops/commits/I10692-structured-citations/
• https://github.com/GaziYucel/pkp-lib/commits/I10692-structured-citations/
• https://github.com/GaziYucel/ui-library/commits/I10692-structured-citations/
• https://github.com/GaziYucel/googleScholar/commits/I10692-structured-citations/
• https://github.com/GaziYucel/jatsTemplate/commits/I10692-structured-citations/
• https://github.com/GaziYucel/crossrefReferenceLinking/commits/I10692-structured-citations/
• https://github.com/GaziYucel/opencitations

Backend UI

https://www.youtube.com/watch?v=yWpQ1GNexow

Schema Citation

• id: id of citation
• publicationId: id of publication
• seq: position or sequence of citation in citation list
• authors: array of objects { displayName, givenName, familyName, orcid, wikidata, openalex }
• doi: The DOI itself, such as 10.1234/5a6b-7c8d.
• rawCitation: citation in raw form
• title: The title of the work.
• date: The publication date, formatted as an ISO 8601 date e.g. 2018-02-13.
• type: The type or genre of the work, e.g. journal-article.
• volume: The volume of the issue of the journal, e.g. 495.
• issue: The issue of the journal, e.g. 7442.
• firstPage: The first page of the work/article, e.g. 49.
• lastPage: The last page of the work/article, e.g. 59.
• sourceName: Name of the source, e.g. journal name
• sourceIssn: Issn_l of the source, e.g. journal issn_l
• sourceHost: Publisher name of the host, e.g. publisher name
• sourceType: Type of the source, e.g. journal, book
• url: URL for the work.
• urn: URN for the work.
• arxiv: Arxiv id / url.
• handle: Handle id / url.
• openAlex: OpenAlex id / url.
• wikidataId: Wikidata qid / url.
• isStructured: Whether this citation is structured or not.
• lastModified: last modified date

Schema Publication

• useStructuredCitations: Whether or not to use the structured citations.

[Tribunal33]

If possible could we put some sample references with expected outcomes in the main requirements section for testing purposes? Don't know if something like that is already going to be an automated cypress test but would be a good candidate.

[asmecher]

Moving this off to 3.5.0-x -- the infrastructural accommodations have been merged for 3.5.0-0, but the feature needs ongoing work.