New study.yml format #13844

turhantolgaunal · 2025-09-09T17:02:32Z

The study.yml is refactored to a new format to implement SEMVER versioning, variable 'databases' is renamed to 'catalogues' for UI consistency.

In the course of working on this draft pull request the query structure is planned to be enhanced to support multiple query formats including catalog-specific variations.

Steps to test

The study.yml file created when a new slr is started should be in a new format and slr search should function as intended.
New format is:
version: 2.0
authors:

author
title: title
research-questions:
question
queries:
query: (author="author" AND title="title")
description: null
lucene: null
catalogue-specific: null
catalogues:
name: ArXiv
enabled: true
metadata:
notes: null
created-date: null
last-modified: null

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.

…ther classes

…ml migrations

…ns from the current study.yml version to the new one

…y.yml file

…n and parsing of study.yml if needed

…r to avoid deadlock

…igrator to JSpecify annotations

…nstead of StudyYamlParser

…ith the rest of the codebase

jablib/src/main/java/org/jabref/logic/crawler/StudyRepository.java

…as not needed

… from getCatalogSpecific form StudyQuery

trag-bot · 2025-09-16T19:47:05Z

jabgui/src/test/java/org/jabref/gui/slr/ManageStudyDefinitionViewModelTest.java

@@ -8,7 +8,7 @@
 import org.jabref.logic.importer.ImportFormatPreferences;
 import org.jabref.logic.importer.ImporterPreferences;
 import org.jabref.model.study.Study;
-import org.jabref.model.study.StudyDatabase;
+import org.jabref.model.study.StudyCatalog;


The import statement for StudyCatalog is correct, but the patch does not address the need to use JavaFX ObservableLists for better practice in managing lists in JavaFX applications.

trag-bot · 2025-09-16T19:47:10Z

jabgui/src/test/java/org/jabref/gui/slr/ManageStudyDefinitionViewModelTest.java

@@ -92,14 +92,14 @@ void studyConstructorFillsDatabasesCorrectly(@TempDir Path tempDir) {
    }

    private ManageStudyDefinitionViewModel getManageStudyDefinitionViewModel(Path tempDir) {
-        List<StudyDatabase> databases = List.of(
-                new StudyDatabase("ACM Portal", true));
+        List<StudyCatalog> catalogs = List.of(


The code uses List.of() which is correct, but it does not utilize JavaFX ObservableLists, which is considered best practice for managing lists in JavaFX applications.

trag-bot · 2025-09-16T19:49:26Z

jabgui/src/main/java/org/jabref/gui/slr/StartNewStudyAction.java

-        StudyYamlParser studyYAMLParser = new StudyYamlParser();
-        studyYAMLParser.writeStudyYamlFile(newStudy, studyRepositoryRoot.resolve(StudyRepository.STUDY_DEFINITION_FILE_NAME));
+        StudyYamlService studyYamlService = new StudyYamlService();
+        studyYamlService.writeStudyYamlFile(newStudy, studyRepositoryRoot.resolve(StudyRepository.STUDY_DEFINITION_FILE_NAME));


The method writeStudyYamlFile should ensure it does not return null. If it does, it should use java.util.Optional to handle potential null values.

jablib/src/main/java/org/jabref/logic/crawler/StudyYamlV1Migrator.java

trag-bot · 2025-09-17T18:58:50Z

jablib/src/main/java/org/jabref/logic/crawler/StudyYamlMigrator.java

+
+        if (CURRENT_VERSION.equals(version)) {
+            // Already current version, read the file normally
+            try (InputStream fileInputStream = Files.newInputStream(studyYamlFile)) {


The try block covers the entire method, which is against best practices. It should cover as few statements as possible to minimize the scope of potential exceptions.

jablib/src/main/java/org/jabref/logic/crawler/StudyYamlV1Migrator.java

Siedlerchr · 2025-10-14T17:56:54Z

jablib/build.gradle.kts

    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310")
    // TODO: Somwewhere we get a warning: unknown enum constant Id.CLASS reason: class file for com.fasterxml.jackson.annotation.JsonTypeInfo$Id not found
    // implementation("com.fasterxml.jackson.core:jackson-annotations:2.19.1")
+    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.15.2")


Put the version in versions/build.gradle

Siedlerchr

lgtm so far

Version in versions/build.gradle is required.

calixtus

Small issue about lucene open, but to move forward should be merged and done in a followup.

* upstream/main: Revert "Issue676 author last (JabRef#13625)" (JabRef#14123) Issue676 author last (JabRef#13625)

* upstream/main: New study.yml format (JabRef#13844) Separate issue linking workflows, make them run on `edited` (JabRef#14121)

koppor · 2025-10-25T14:17:22Z

jablib/src/main/java/org/jabref/logic/crawler/StudyYamlMigrator.java

+ * Provides common functionality for version detection
+ * and handles the migration process
+ */
+


Why emtpy line here?

koppor · 2025-10-25T14:20:48Z

jablib/src/test/java/org/jabref/logic/crawler/StudyYamlV1MigratorTest.java

+    }
+
+    @Test
+    void migrateEmptyStudySuccessfully() throws IOException {


Wrong approach, there should be two YAML files compared. Not input. YAML content and output: data model.

This reverts commit db1e651.

koppor · 2025-10-30T18:57:57Z

We reverted this PR as not everything from the issue was done. We want to have a new intermediate release - and we cannot include some unfinished work. Sorry @turhantolgaunal that we are currently understaffed for this and you did not get any feedback in time. Maybe, another contributor builds on your work.

The last two bullets points of the issue were not done

Moreover, tests were missing reading in the new YAML file structure.

Tests should also go from strings to strings - not from strings to data model and vice versa.

This reverts commit db1e651.

* Reformatted database variable to catalogue * Renamed StudyDatabase.java to StudyCatalog and updated its usage in other classes * Created an abstract StudyYamlMigrator class as a template for study.yml migrations * Created an implementation of the abstract Migrator class for migrations from the current study.yml version to the new one * Created a StudyMetadata class to handle the metadata part of the study.yml file * Created a new class called StudyYamlService for handling the migration and parsing of study.yml if needed * StudyYamlMigrator no longer uses child classes in constructor in order to avoid deadlock * Ran openrewrite and changed the jetbrains annotations in StudyYamlV1Migrator to JSpecify annotations * Changed StudyYamlParserTest.java to use the new StudyYamlParserTest instead of StudyYamlParser * Changed the usage of the word catalogue to catalog to be consistent with the rest of the codebase * Added functions for adding a metadata field to the study.yml * Added unit tests for MigratorV1, removed the study type field as it was not needed * Changed database variable to catalog and an immutable map is returned from getCatalogSpecific form StudyQuery * Reformatted files * Removed studytype parameter in StudyMetadata * yaml mapper variable in StudyYamlMigrator is now a static field * Changed null handling on some variables to use Optional * Changed the use of StringBuilder to StringJoiner in StudyYamlV1Migrator * Added Optionals to various functions * Refactored the tests for StudyYamlV1Migrator to use Optionals correctly * Refactored the tests for StudyYamlV1Migrator to use Optionals correctly * Refactored the tests for StudyYamlV1Migrator to use Optionals correctly * Refactored StudyQuery to not use collections import * Disabled the requirement for handlers for java8 optionals in StudyYamlParser * Reverted the disabling of the requirement for handlers for optionals in StudyYamlParser and removed Optionals in StudyQuery * Changed the usage of Optionals in Study and readded Optionals on StudyQuery * Added new dependency jackson datatype jdk 8 for serializing Optionals * Refactored Study and StudyQuery to use more Optionals, StudyYamlParser should support proper deserialization of Optionals * Added annotations for Json deserialization to avoid conflicts * getCatalogSpecificOptional function is ignored when deserializing Json * updated StudyQuery equals method for compatibility with testing * Update jablib/src/main/java/org/jabref/logic/crawler/StudyYamlV1Migrator.java Co-authored-by: Carl Christian Snethlage <[email protected]> * Reverted the update to instanceof check because of unsafe type conversion * Added nonnull annotations and changed the metadata field to not use Optional * Added nonnull annotations to getVersion function from StudyYamlV1Migrator * Changed the suppress warning annotation to the whole function in StudyYamlV1Migrator * fix version and remove unused stuff * readd --------- Co-authored-by: Carl Christian Snethlage <[email protected]> Co-authored-by: Christoph <[email protected]>

This reverts commit db1e651.

Reformatted database variable to catalogue

cae829c

turhantolgaunal changed the title ~~Reformatted database variable to catalogue~~ New study.yml format Sep 9, 2025

turhantolgaunal added 12 commits September 12, 2025 20:26

Renamed StudyDatabase.java to StudyCatalog and updated its usage in o…

2921b60

…ther classes

Created an abstract StudyYamlMigrator class as a template for study.y…

1f4a76c

…ml migrations

Created an implementation of the abstract Migrator class for migratio…

4fc5972

…ns from the current study.yml version to the new one

Created a StudyMetadata class to handle the metadata part of the stud…

5c0f359

…y.yml file

Created a new class called StudyYamlService for handling the migratio…

4117dd0

…n and parsing of study.yml if needed

StudyYamlMigrator no longer uses child classes in constructor in orde…

a257409

…r to avoid deadlock

Ran openrewrite and changed the jetbrains annotations in StudyYamlV1M…

6ca6a9c

…igrator to JSpecify annotations

Changed StudyYamlParserTest.java to use the new StudyYamlParserTest i…

ea1df6d

…nstead of StudyYamlParser

Merge branch 'main' into newstudyyaml

4d647b0

Changed the usage of the word catalogue to catalog to be consistent w…

75cd28f

…ith the rest of the codebase

Merge remote-tracking branch 'origin/newstudyyaml' into newstudyyaml

0938051

Added functions for adding a metadata field to the study.yml

89d53d2

trag-bot bot reviewed Sep 14, 2025

View reviewed changes

jablib/src/main/java/org/jabref/logic/crawler/StudyRepository.java Show resolved Hide resolved

turhantolgaunal and others added 3 commits September 16, 2025 22:03

Added unit tests for MigratorV1, removed the study type field as it w…

837a7b5

…as not needed

Changed database variable to catalog and an immutable map is returned…

4167044

… from getCatalogSpecific form StudyQuery

Merge branch 'JabRef:main' into newstudyyaml

be06340

trag-bot bot reviewed Sep 16, 2025

View reviewed changes

turhantolgaunal and others added 2 commits September 17, 2025 20:28

Merge branch 'JabRef:main' into newstudyyaml

b210e1e

Reformatted files

6a1326e

trag-bot bot reviewed Sep 17, 2025

View reviewed changes

jablib/src/main/java/org/jabref/logic/crawler/StudyYamlV1Migrator.java Outdated Show resolved Hide resolved

turhantolgaunal added 2 commits September 17, 2025 21:50

Removed studytype parameter in StudyMetadata

23f3bb6

yaml mapper variable in StudyYamlMigrator is now a static field

950af58

trag-bot bot reviewed Sep 17, 2025

View reviewed changes

turhantolgaunal added 2 commits September 17, 2025 22:04

Changed null handling on some variables to use Optional

9bdc084

Changed the use of StringBuilder to StringJoiner in StudyYamlV1Migrator

e7f35dd

trag-bot bot reviewed Sep 17, 2025

View reviewed changes

jablib/src/main/java/org/jabref/logic/crawler/StudyYamlV1Migrator.java Show resolved Hide resolved

Siedlerchr reviewed Oct 14, 2025

View reviewed changes

Siedlerchr previously approved these changes Oct 14, 2025

View reviewed changes

Siedlerchr requested a review from koppor October 14, 2025 17:57

Siedlerchr added the status: ready-for-review Pull Requests that are ready to be reviewed by the maintainers label Oct 14, 2025

Merge branch 'main' into newstudyyaml

2d39d82

Siedlerchr enabled auto-merge October 20, 2025 18:44

Siedlerchr previously approved these changes Oct 20, 2025

View reviewed changes

Siedlerchr added this pull request to the merge queue Oct 20, 2025

Siedlerchr removed this pull request from the merge queue due to a manual request Oct 20, 2025

fix version and remove unused stuff

c0596ee

Siedlerchr dismissed their stale review via c0596ee October 20, 2025 18:50

readd

40f79ed

calixtus approved these changes Oct 20, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/main' into newstudyyaml

cd4e27f

* upstream/main: Revert "Issue676 author last (JabRef#13625)" (JabRef#14123) Issue676 author last (JabRef#13625)

Siedlerchr enabled auto-merge October 20, 2025 19:24

Siedlerchr added this pull request to the merge queue Oct 20, 2025

Merged via the queue into JabRef:main with commit db1e651 Oct 20, 2025
47 checks passed

github-actions bot mentioned this pull request Oct 20, 2025

New study.yml format #12642

Open

Siedlerchr added a commit to Yubo-Cao/jabref that referenced this pull request Oct 20, 2025

Merge remote-tracking branch 'upstream/main' into fix/786

3702c81

* upstream/main: New study.yml format (JabRef#13844) Separate issue linking workflows, make them run on `edited` (JabRef#14121)

koppor reviewed Oct 25, 2025

View reviewed changes

koppor mentioned this pull request Oct 25, 2025

Review studyv2 YAML format, if it is really correct #14170

Open

4 tasks

koppor added a commit that referenced this pull request Oct 30, 2025

Revert "New study.yml format (#13844)"

fb3817d

This reverts commit db1e651.

koppor mentioned this pull request Oct 30, 2025

Revert "New study.yml format" #14204

Merged

github-merge-queue bot pushed a commit that referenced this pull request Oct 30, 2025

Revert "New study.yml format (#13844)" (#14204)

546e041

This reverts commit db1e651.

merlinymy pushed a commit to merlinymy/jabref that referenced this pull request Nov 19, 2025

Revert "New study.yml format (JabRef#13844)" (JabRef#14204)

0a32b7e

This reverts commit db1e651.

Uh oh!

New study.yml format #13844

New study.yml format #13844

Uh oh!

Conversation

turhantolgaunal commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Steps to test

Mandatory checks

Uh oh!

Uh oh!

trag-bot bot Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

trag-bot bot Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Siedlerchr Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Siedlerchr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

calixtus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

koppor Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

koppor commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

turhantolgaunal commented Sep 9, 2025 •

edited

Loading

Siedlerchr Oct 14, 2025 •

edited

Loading