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

[Christoph Heiss]

On Tue, Nov 12, 2024 at 02:44:48PM +0100, Thomas Lamprecht wrote:
> Am 12.11.24 um 14:18 schrieb Christoph Heiss:
> > [..]
> > --- 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")]
>
> maybe still use $format-version or $hook-version or the like for the
> serialized key? I.e., to even better convey that this is, e.g., not some
> version from the installer or product.

What do you think about

    "$hook": { "version": "1.0" }`

maybe, thereby making it a bit more structured from the start?
Esp. when thinking about future expansions, if we ever want to add
additional metadata fields.

As we're already on the topic of future changes.

But no hard feelings, otherwise I'd just go with `$hook-version`.

>
> Albeit a hook-version would be probably sent along as HTTP header, as
> that then would even bigger change, but as a) it's rather unlikely that
> we change away from JSON and b) the absence of such a header can be used
> as v0, it is probably overkill now.

Also, sending as HTTP header would most likely complicate implementing
a server somewhat, depending on the tool/framework used. IOW, having it
in the document directly is quite useful IMO.

But it's a nice idea for the future to have, if we ever need something
like this.