Add check if correct schemas are present in the reachability metadata repository provided to buildtools by jormundur00 · Pull Request #821 · graalvm/native-build-tools

jormundur00 · 2026-01-20T09:58:47Z

In this PR we introduce validation that correct schemas (that are of a certain major version) are present in the reachability metadata repository provided to the buildtools. With this check, we can warn the user if the format of the metadata repository they are using is outdated and will not work with the current buildtools.

As the changes within the schemas might not require changes in the buildtools repo, we only check if the major version matches, as those version changes represent changes that are not compatible with previous buildtools releases (e.g., adding a new field to a schema that isn't used by buildtools doesn't require buildtools changes).

This PR is a prerequisite for changing the index.json parsing done by the buildtools, as not having this check could lead to projects who use older metadata snapshots breaking without knowing why.

Fixes: #820

… repo provided to buildtools

vjovanov · 2026-01-21T08:14:29Z

...src/main/java/org/graalvm/buildtools/gradle/internal/GraalVMReachabilityMetadataService.java


    private FileSystemRepository newRepositoryFromDirectory(Path path, LogLevel logLevel) {
        if (Files.isDirectory(path)) {
+            SchemaValidationUtils.validateSchemas(path);


Do we have GraalVM home at this point?

This happens pretty early on and we don't have the knowledge of GraalVM home here.

vjovanov · 2026-01-21T08:18:03Z

native-maven-plugin/src/main/java/org/graalvm/buildtools/maven/AbstractNativeMojo.java

                    "Note: Since the repository is enabled by default, you can disable it manually in your pom.xml file (see this: " +
                    "https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#_configuring_the_metadata_repository)");
        } else {
+            SchemaValidationUtils.validateSchemas(repoPath);


Why don't we have a single place where we validate?

I moved the validation to inside of the FileSystemRepository constructor, so we can now do it in one place for both of the plugins. This required me to add a dependency from the common/graalvm-reachability-metadata project to the common/utils project, but that seems like a reasonable addition to me, as I see no reason to not have a dependency on Utils.

vjovanov · 2026-01-21T08:18:36Z

...ve-config-integration/config-directory/schemas/library-and-framework-list-schema-v1.0.0.json

@@ -0,0 +1,4 @@
+{
+  "name": "library-and-framework-list-schema-v1.0.0",
+  "note": "placeholder for tests"


What does this mean?

Since we now require schemas, we have to also add them to all the "custom" repositories that the tests use. As not to have to always copy the exact schema content (as I don't see a reason to), I just left a placeholder text.

To avoid even more confusion, I changed the content of these schemas to just being [].

vjovanov · 2026-01-21T08:22:11Z

common/utils/src/main/java/org/graalvm/buildtools/utils/SchemaValidationUtils.java

+        // Validate required files in the schemas directory (accepting minimal versions or newer)
+        List<String> missing = new ArrayList<>();
+        String prefix = repoRoot.relativize(schemasDir).toString();
+        for (RequiredSchema required : REQUIRED_SCHEMAS) {


What happens if we add a new schema in the metadata repo? We should match the two sets I believe and if there is an extra version, or the version in the repo is bigger you should update the build tools.

Counting the number of schemas provided by the metadata repo seems reasonable to me (since changing the number of packaged schemas SHOULD require buildtools changes), so I added that.

I don't think we should necessarily fail if the schema version provided by the metadata repo is higher than the one in build tools: adding some field in an index.json which is not used by buildtools (for example, the field denoting metadata has been generated by AI, which we plan to add) should not necessitate buildtools updates (as it has no effect on them). If we were to go the EXACT match route, we would have to update buildtools every time any small change happens to any of the schemas, which I don't think is maintainable. A solution I came up with was to just keep the minimal version in buildtools, and fail if the metadata provided schemas are lower than the minimal required. Buildtools releases generally come with hardcoded metadata repo versions, so users using an old buildtools release with new metadata versions should do that at their own peril IMO.

then we need to make the changes to the schemas forward compatible right so we need to have a way to tell to the build tools you need to update. Are we going to be backwards compatible in the repo?

Per our offline discussion, I changed it so we now check for EXACT matches in the major version of the schemas. If either the metadata repo or the buildtools-requires have a higher major version, we now fail the builds and leave the appropriate update suggestion in the error message (so now we have a message for every different scenario of version mismatches).

vjovanov · 2026-01-22T13:10:33Z

...chability-metadata/src/main/java/org/graalvm/reachability/internal/FileSystemRepository.java

-        this.rootDirectory = rootDirectory;
-    }
+            SchemaValidationUtils.validateSchemas(rootDirectory);
+            this.moduleIndex = new FileSystemModuleToConfigDirectoryIndex(rootDirectory);


Indentation looks bad.

vjovanov · 2026-01-22T13:11:24Z

...ility-metadata/src/test/resources/repos/repo2/schemas/metadata-root-index-schema-v1.0.0.json

@@ -0,0 +1 @@
+{}


Why even have a file, especially a file with a missing end-of-line?

These /resources/repos directories are "mock" metadata repositories used in testing. As we now require the metadata repositories to have certain schemas packaged with them (and we check this), we need to add this "mock" schema directory inside of them.

The missing end-of-line got mixed in somehow with AI generation, I've added them now.

vjovanov · 2026-01-23T11:11:38Z

common/utils/src/main/java/org/graalvm/buildtools/utils/SchemaValidationUtils.java

+    /**
+     * Represents a required schema by base name with an exact required major version.
+     */
+    private record RequiredSchema(String baseName, int requiredMajor) {


requiredMajorVersion

jormundur00 requested a review from vjovanov January 20, 2026 09:58

jormundur00 self-assigned this Jan 20, 2026

oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Jan 20, 2026

Add check if correct schemas are present in the reachability metadata…

ab18b95

… repo provided to buildtools

jormundur00 force-pushed the jormundur00/gh-820 branch 2 times, most recently from 0bba771 to 7101367 Compare January 20, 2026 10:37

Fix tests to include new schemas/use new repository versions

08f31ec

jormundur00 force-pushed the jormundur00/gh-820 branch from 7101367 to 08f31ec Compare January 20, 2026 10:41

vjovanov reviewed Jan 21, 2026

View reviewed changes

jormundur00 added 2 commits January 21, 2026 09:57

Move schema validation to one location

648ac61

Enforce a strict schema count

ddbf9bb

vjovanov reviewed Jan 22, 2026

View reviewed changes

jormundur00 added 2 commits January 22, 2026 14:18

Fix wrong indentation and missing newlines

a9e62b0

Make SchemaValidationUtils check for EXACT major versions

e557605

jormundur00 force-pushed the jormundur00/gh-820 branch from 43ff9bd to e557605 Compare January 23, 2026 08:57

vjovanov reviewed Jan 23, 2026

View reviewed changes

vjovanov previously approved these changes Jan 23, 2026

View reviewed changes

Change field name to be more accurate

62fe7f1

jormundur00 dismissed vjovanov’s stale review via 62fe7f1 January 23, 2026 11:15

vjovanov approved these changes Jan 23, 2026

View reviewed changes

melix approved these changes Jan 23, 2026

View reviewed changes

jormundur00 merged commit f8eb50d into master Jan 23, 2026
560 checks passed

jormundur00 deleted the jormundur00/gh-820 branch January 23, 2026 12:11

		@@ -0,0 +1 @@
		{} No newline at end of file

Conversation

jormundur00 commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jormundur00 commented Jan 20, 2026 •

edited

Loading