KhronosGroup / KhronosGroup/Vulkan-Loader
Clarify which fields are optional and which are required in layer manifest file
- Dominant language
- C
- Stars
- 695
- Forks
- 343
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 17
Description
Hi,
I think that the current version of the loader spec has some ambiguity about what fields are required in the layers manifest JSON, see the table at https://github.com/KhronosGroup/Vulkan-Loader/blob/b8b96a2862bff1eed468e602d43f706beae89cf1/docs/LoaderLayerInterface.md#layer-manifest-file-format
For example, from a first read it was not clear to me whether the `description` field was **required**, I had to read between the lines, and get confirmation from the loader reference implementation at https://github.com/KhronosGroup/Vulkan-Loader/blob/b8b96a2862bff1eed468e602d43f706beae89cf1/loader/loader.c#L2792-L2801which was not immediate.
While it can be argued that optional fields are labeled as **OPTIONAL:** in the `Description and Notes` column, and hence non-optional fields are required, this looks too informal and may leave room for ambiguity.
For comparison, in the OpenXR spec the correspondent table has a **dedicated column** to explicitly specify whether a field is required or optional, see the table at https://registry.khronos.org/OpenXR/specs/1.1/loader.html#api-layer-manifest-file-format
Can a something similar be added to the Vulkan Layers manifest format spec too?
If there is interest I can draft a patch. Would changing `LoaderLayerInterface.md` be enough? Or should I look somewhere else too?
Thanks, Antonio
Contributor guide
Research direction
Start with docs/LoaderLayerInterface.md and inspect the layer manifest file format table referenced in the issue. Compare its field descriptions with the loader.c lines linked in the report and the OpenXR table, then make the required-versus-optional status explicit and verify whether the documentation change belongs only in that file.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 78/100