KhronosGroup / KhronosGroup/Vulkan-Loader

Clarify which fields are optional and which are required in layer manifest file

Open Beginner friendly
#2,030 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.