[GR-70727] Add dynamic access metadata JSON file schema

PullRequest: graal/22517

Author: jormundur00

docs/reference-manual/native-image/BuildReport.md

@@ -203,9 +203,10 @@ After building your application, open the generated report (for example, _target
 
 This section of the report highlights code that may require review to ensure your application runs successfully as a native executable. For example, classes loaded via `Class.forName(...)` must be included in the executable.
 
-**Understanding the Dynamic Access tab:**
+### Understanding the Dynamic Access Tab
 
 - If no dynamic calls are detected for a class or module path entry, no further action is needed.
+- If another entry provides metadata for this entry, no further investigation is needed.
 - If the entry includes `native-image.properties` or `reachability-metadata.json`, or these files are provided externally, no further investigation is required.
 - If integrated configuration or external metadata (such as `reflect-config.json`) exists for each detected call type, no further investigation is required.
 - If none of the above apply, the entry may require further investigation.
@@ -214,6 +215,19 @@ For each entry with detected dynamic calls, you can expand the entry in the repo
 
 > Only dynamic calls found in reachable code are reported. Some entries may have existing metadata but no reported dynamic calls.
 
+### Dynamic Access Metadata
+
+The Dynamic Access tab uses a `dynamic-access-metadata.json` file that maps which classpath entries provide reachability metadata for other entries. Place this file on your classpath for the Build Report to automatically discover metadata relationships between different classpath entries.
+
+The schema includes the following keys:
+
+* `metadataProvider`: The absolute path to the JAR or directory that provides reachability metadata
+* `providesFor`: An array of classpath entries that receive metadata from this provider
+
+For the complete JSON schema specification, see the [_dynamic-access-metadata-v1.0.0.json_ file](https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/assets/dynamic-access-metadata-v1.0.0.json){:target="_blank"}.
+
+The Build Report uses this information to create a comprehensive view of metadata relationships and highlight potential coverage gaps.
+
 For a practical demonstration of running and using the `-H:+ReportDynamicAccess` option, see the [preserve-package demo](https://github.com/graalvm/graalvm-demos/tree/master/native-image/preserve-package).
 
 ## Related Documentation

docs/reference-manual/native-image/assets/dynamic-access-metadata-schema-v1.0.0.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/assets/dynamic-access-metadata-v1.0.0.json",
+  "title": "JSON schema for library support metadata used by the Dynamic Access tab of the GraalVM Native Image Build Report",
+  "version": "1.0.0",
+  "type": "array",
+  "default": [],
+  "items": {
+    "type": "object",
+    "required": ["metadataProvider", "providesFor"],
+    "properties": {
+      "metadataProvider": {
+        "type": "string",
+        "title": "The classpath entry (JAR or directory) providing reachability metadata",
+        "pattern": "^/.+"
+      },
+      "providesFor": {
+        "type": "array",
+        "title": "List of classpath entries that this provider contributes metadata for",
+        "default": [],
+        "items": {
+          "type": "string",
+          "pattern": "^/.+"
+        }
+      }
+    },
+    "additionalProperties": false
+  },
+  "examples": [
+    [
+      {
+        "metadataProvider": "/home/user/.m2/repository/org/springframework/boot/spring-boot-starter-web/3.5.6/spring-boot-starter-web-3.5.6.jar",
+        "providesFor": [
+          "/home/user/.m2/repository/org/slf4j/slf4j-api/2.0.17/slf4j-api-2.0.17.jar",
+          "/home/user/.m2/repository/org/springframework/spring-context/6.2.11/spring-context-6.2.11.jar"
+        ]
+      },
+      {
+        "metadataProvider": "/home/user/.m2/repository/org/springframework/boot/spring-boot-starter-data-jpa/3.5.6/spring-boot-starter-data-jpa-3.5.6.jar",
+        "providesFor": [
+          "/home/user/.m2/repository/org/hibernate/orm/hibernate-core/6.6.29.Final/hibernate-core-6.6.29.Final.jar"
+        ]
+      }
+    ]
+  ]
+}