[GR-54193] Improve docs on JSON config files

[nreid260]

Feature request

Is your feature request related to a problem? Please describe.

My main point of reference is this page https://www.graalvm.org/latest/reference-manual/native-image/metadata/ There are a few problems:

• There are 6 schemas listed on that page but there appear to be other, undocumented config files e.g. access-filter.json excludes most, but not all files when using a descendants pattern #3174
• All of the links to the schemas on that page are for version 1.0.0, but new fields seem to have been added e.g. [GR-37224] Support for Unsafe.allocateInstance in NI #4393 Where can I find up-to-date schemas?
  • Also the existing JSON schemas are pretty terrible to read as a human, but I could accept that as long as they're accurate
• The schemas are not linked from the very similar documentation pages at https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/ which are inconsistent with the first page

Describe the solution you'd like.

I'd like:

• Documentation to list all schemas
• Up-to-date schema links
  • These could point to the latest revision, or docs for different versions should link to the appropriate schema version
• Consolidation of the https://www.graalvm.org/latest/reference-manual/native-image/metadata/ and https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/ docs, which cover a lot of the same material

Describe who do you think will benefit the most.
GraalVM users. The existing docs are difficult to navigate and present conflicting information.

Describe alternatives you've considered.

Publishing the config schemas using a stongly typed format (e.g. protobuf) would be very handy. It would:

• be easier to read
• enable trusting the schema as the source-of-truth about the format
• eliminate the handwritten config parser classes

Additional context.

https://protobuf.dev/programming-guides/proto2/

Express whether you'd like to help contributing this feature

I have already written protobuf schema files. I plan to express all our config files as https://protobuf.dev/reference/protobuf/textformat-spec/ and convert them into the JSON format. I could share these if desired.

[selhagani]

Hi @nreid260 Thank you for your feature request regarding GraalVM documentation and schema accessibility. I will share your suggestions and offer to contribute protobuf schema files with our team.

[vjovanov]

Thanks for reporting! The plan is to do the documentation overhaul in August and stay tuned. CC @loicottet