Link the schema from the documentation

Author: vjovanov

docs/reference-manual/native-image/assets/reachability-metadata-schema-v1.2.0.json

@@ -1 +1 @@
-reachability-metadata-schema-v1.2.0.json
+../../../../substratevm/schemas/reachability-metadata-schema-v1.2.0.json

substratevm/CHANGELOG.md

@@ -8,6 +8,8 @@ This changelog summarizes major changes to GraalVM Native Image.
 * (GR-69280) Allow use of the `graal.` prefix for options without issuing a warning.
 * (GR-2092) Add jitdump support for recording run-time compilation metadata for perf (see PerfProfiling.md). Can be enabled with `-g -H:+RuntimeDebugInfo -H:RuntimeDebugInfoFormat=jitdump`.
 * (GR-69572) Deprecates the `native-image-inspect` tool. To extract embedded SBOMs, use `native-image-configure extract-sbom --image-path=<path_to_binary>`.
+* (GR-68984) Ship the `reachability-metadata-schema.json` together with GraalVM at `<graalvm-home>/lib/svm/schemas/reachability-metadata-schema.json`.
+* (GR-68984) Improve the schema to capture detailed constraints about each element in the `reachability-metadata-schema.json`.
 
 ## GraalVM 25
 * (GR-52276) (GR-61959) Add support for Arena.ofShared().

substratevm/mx.substratevm/mx_substratevm.py

@@ -2494,6 +2494,48 @@ def compute_graal_compiler_flags_map(self):
 
         return graal_compiler_flags_map
 
+def get_jsonschema_validator(schema_path):
+    """Create and return a jsonschema Validator for the schema at the given file path. Abort on missing jsonschema or invalid schema."""
+    import json
+    try:
+        with open(schema_path, "r", encoding="utf-8") as f:
+            schema = json.load(f)
+    except json.JSONDecodeError as e:
+        mx.abort(f'Failed to parse JSON in schema file "{schema_path}" at line {e.lineno}, column {e.colno}: {e.msg}')
+    except OSError as e:
+        mx.abort(f'I/O error when opening schema file "{schema_path}": {e}')
+
+    try:
+        import jsonschema  # type: ignore
+    except ImportError as e:
+        mx.abort(
+            'Python module "jsonschema" is required to validate reachability metadata but was not found. '
+            'Install it with: "python3 -m pip install --user jsonschema" (or "pip3 install jsonschema"). '
+            f'Original error: {e}')
+    try:
+        if hasattr(jsonschema, 'Draft202012Validator'):
+            return jsonschema.Draft202012Validator(schema)  # type: ignore[attr-defined]
+        else:
+            return jsonschema.Draft7Validator(schema)  # type: ignore
+    except (jsonschema.exceptions.SchemaError, TypeError) as e:
+        mx.abort(f'Invalid reachability metadata schema: {e}')
+
+def validate_json_file_against_schema(validator, file_path):
+    """Validates a JSON file against the provided Validator. Returns a list of error strings; empty if valid."""
+    import json
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        mx.abort(f'Invalid JSON syntax at line {e.lineno}, column {e.colno}: {e.msg}')
+    except OSError as e:
+        mx.abort(f'I/O error: {e}')
+
+    errors = []
+    for err in validator.iter_errors(data):
+        path = '/'.join([str(p) for p in err.path]) if err.path else '#'
+        errors.append(f'{path}: {err.message}')
+    return errors
 
 class SubstrateCompilerFlagsBuildTask(mx.ArchivableBuildTask):
     def __init__(self, subject, args):

substratevm/mx.substratevm/suite.py

@@ -2475,7 +2475,7 @@
                 "clibraries/" : ["extracted-dependency:substratevm:SVM_HOSTED_NATIVE"],
                 "builder/clibraries/" : ["extracted-dependency:substratevm:SVM_HOSTED_NATIVE"],
                 "builder/lib/" : ["dependency:com.oracle.svm.native.reporterchelper"],
-                "schemas/reachability-metadata-schema.json" : ["file:docs/schemas/reachability-metadata-schema-v1.2.0.json"],
+                "schemas/reachability-metadata-schema.json" : ["file:schemas/reachability-metadata-schema-v1.2.0.json"],
                 # Note: `ld64.lld` is a symlink to `lld`, but it is dereferenced here.
                 "bin/" : ["extracted-dependency:LLVM_LLD_STANDALONE/bin/ld64.lld"],
             },