metadata documentation incomplete

***In GitLab by @fuegotest on Oct 14, 2021, 18:40 GMT+1:***

I am trying to examine the metadata that tuxmake creates, to write supporting code that utilizes the information. I examined the page https://www.tuxmake.org/metadata/, and it has text descriptions of various fields in the metadata.json file. A few things I was interested in were missing from the
documentation on that page. Specifically, it doesn't list the possible items under results.artifacts.

By examining the metadata.json file at https://builds.tuxbuild.com/1z7itFPn0r4Tjsr0YeAdS922Lqw/, I was able to see the attributes: "config", "dtbs", "headers", and "log". I was left wondering what the name for the attribute that indicated what the kernel image was. Apparently this link was for a build that did not produce a kernel, and that attribute was missing.

I downloaded tuxmake and did my own build, and noted the following results.artifacts in the metadata.json file for the build:
"config", "debugkernel", "default", "dtbs", "dtbs-legacy", "headers", "kernel", "log", "modules", and "xipkernel". These attributes all appear to be arrays. In the case of a "debugkernel", the second item in the array appears to be the System.map file for the debug kernel.

I have a few questions based on what I saw:

1) If the metadata.json file is sparse (which it appears from the description on https://www.tuxmake.org/metadata, and from the metadata.json file for the failed build), then why are some results.artifacts empty in my local build. e.g. I saw
"dtbs": [] in my x86_64 local build metadata.json file. Basically, I'm a bit
confused whether the convention is to omit fields for missing files or have the
attributes in metadata.json be empty.

2) Does the name of the kernel image file differ depending on build parameters?
I got a "kernel" of "bzImage" on my local build. Do other builds (or build targets) produce different kernel image types (and names)?

IMHO, it would be good to add a link to a complete (fully populated) metadata.json file, as an example, from the https://www.tuxmake.org/metadata page. Also, it
would be nice to have a json schema file somewhere, to describe each of the attributes and their possible values. (The entry for "System.map" is not documented, and IMHO is a bit confusing. Is this always the 2nd element of the array of items
for the results.artifacts.debugkernel attribute? Can the array of items for each
artifact contain other things that are not documented? If so, which ones, and what
items?

Finally, IMHO it would be good to mention somewhere on https://www.tuxmake.org/metadata that the strings for filenames or filepaths in
the metadata.json file are relative to the directory where the metadata.json file resides (e.g. on the same server, or in the same file system). The meaning of the metadata.json contents is dependent on where it resides in the filesystem. (ie, you can't just move the metadata.json file somewhere else, by itself, and use it.)

Just my 2 cents.
-- Tim

**Assignees:** bhcopeland

*Migrated from GitLab: https://gitlab.com/Linaro/tuxmake/-/issues/157*

Start by reviewing the metadata documentation at https://www.tuxmake.org/metadata/ and comparing it with the referenced metadata.json examples. Document the results.artifacts entries, missing-versus-empty behavior, filename paths, and kernel image variants, and add a complete example or schema if supported by the project. Done means the documented fields and artifact conventions answer the questions raised in the issue.

Written by the indexing model from the issue text.