[pve-devel] [PATCH installer] post-hook: add `$version` field describing document schema version

[Christoph Heiss]

This adds a metadata-field `$version` to the post-hook json, indicating
which schema version (and thus structure) this document uses.

The field is of format "<major>.<minor>", following the semantic
versioning meaning for both the major and minor number. A patch version
is left out here, as it doesn't make much sense in this context.

This was suggested by Thomas when originally introducing the post-hook
functionality in [0].

[0] https://lore.proxmox.com/pve-devel/00019f8d-e4f2-420e-892a-b89e8b886748@proxmox.com/

Suggested-by: Thomas Lamprecht <t.lamprecht at proxmox.com>
Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
---
 proxmox-post-hook/src/main.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/proxmox-post-hook/src/main.rs b/proxmox-post-hook/src/main.rs
index 8558da2..fb51ba9 100644
--- a/proxmox-post-hook/src/main.rs
+++ b/proxmox-post-hook/src/main.rs
@@ -133,6 +133,17 @@ struct CpuInfo {
 #[derive(Serialize)]
 #[serde(rename_all = "kebab-case")]
 struct PostHookInfo {
+    /// major.minor version describing the schema version of this document, in a semanticy-version
+    /// way.
+    ///
+    /// major: Incremented for incompatible/breaking API changes, e.g. removing an existing
+    /// field.
+    /// minor: Incremented when adding functionality in a backwards-compatible matter, e.g.
+    /// adding a new field.
+    // This field is prefixed by `$` on purpose, to indicate that it is document metadata and not
+    // part of the actual content itself. (E.g. JSON Schema uses a similar naming scheme)
+    #[serde(rename = "$version")]
+    schema_version: String,
     /// major.minor version of Debian as installed, retrieved from /etc/debian_version
     debian_version: String,
     /// PVE/PMG/PBS version as reported by `pveversion`, `pmgversion` or
@@ -166,6 +177,8 @@ struct PostHookInfo {
 const SIZE_GIB: usize = 1024 * 1024 * 1024;
 
 impl PostHookInfo {
+    const SCHEMA_VERSION: &str = "1.0";
+
     /// Gathers all needed information about the newly installed system for sending
     /// it to a specified server.
     ///
@@ -215,6 +228,7 @@ impl PostHookInfo {
         };
 
         Ok(Self {
+            schema_version: Self::SCHEMA_VERSION.to_owned(),
             debian_version: read_file("/etc/debian_version")?,
             product: Self::gather_product_info(&setup_info, &run_cmd)?,
             iso: setup_info.iso_info.clone(),
-- 
2.47.0