Problem
The Get snapshot API reference declares artifacts as Artifacts · object[] with artifacts[]: type object and no field-level descriptions. None of the fields inside an artifact are documented anywhere. deployment_diff is the clearest case: it appears only as raw example output on the kosli get snapshot client reference page, with no explanation of what it means or when it is present.
Expected Behavior
/api-reference/snapshots/get-snapshot describes the fields of an artifact object, including a deployment_diff object with each sub-field explained:
diff_urlprevious_git_commitprevious_git_commit_urlprevious_fingerprintprevious_artifact_nameprevious_artifact_compliance_stateprevious_runningprevious_trail_nameprevious_template_reference_name
It should also state what "previous" is measured against, when deployment_diff is absent, for example the first time an artifact appears in an environment, and which sub-fields can be null.
Current Behavior
Readers have to reverse-engineer the semantics from a sample payload on the client reference page.
Use Case
Anyone consuming the snapshot API programmatically, for lead-time or change reporting, needs to know whether deployment_diff is a reliable pointer to the artifact it replaced.
Suggested Approach
The descriptions belong in the API schema so the generated reference picks them up, rather than being hand-written on the docs page. This issue covers the docs side once the schema carries them.
Problem
The Get snapshot API reference declares
artifactsasArtifacts · object[]withartifacts[]: type objectand no field-level descriptions. None of the fields inside an artifact are documented anywhere.deployment_diffis the clearest case: it appears only as raw example output on thekosli get snapshotclient reference page, with no explanation of what it means or when it is present.Expected Behavior
/api-reference/snapshots/get-snapshotdescribes the fields of an artifact object, including adeployment_diffobject with each sub-field explained:diff_urlprevious_git_commitprevious_git_commit_urlprevious_fingerprintprevious_artifact_nameprevious_artifact_compliance_stateprevious_runningprevious_trail_nameprevious_template_reference_nameIt should also state what "previous" is measured against, when
deployment_diffis absent, for example the first time an artifact appears in an environment, and which sub-fields can be null.Current Behavior
Readers have to reverse-engineer the semantics from a sample payload on the client reference page.
Use Case
Anyone consuming the snapshot API programmatically, for lead-time or change reporting, needs to know whether
deployment_diffis a reliable pointer to the artifact it replaced.Suggested Approach
The descriptions belong in the API schema so the generated reference picks them up, rather than being hand-written on the docs page. This issue covers the docs side once the schema carries them.