[pve-devel] GET /access/users/{userid} has parameter 'tokens' with 'additionalProperties' containing object definition

[Johannes Draaijer]

Hi,

Right, that makes a lot more sense! So the correct reading is more akin to
"an object that contains unknown keys, but the objects behind those keys
have a known schema"

Thank you for clarifying!

Kind regards,

Johannes

On Tue, Apr 2, 2024 at 10:00 AM Wolfgang Bumiller <w.bumiller at proxmox.com>
wrote:

> On Tue, Apr 02, 2024 at 09:27:57AM +0200, Fabian Grünbichler wrote:
> >
> > > Jona Draaijer via pve-devel <pve-devel at lists.proxmox.com> hat am
> 01.04.2024 22:00 CEST geschrieben:
> > > Hi,
> > >
> > > As per the title, that endpoint has an additionalProperties value that
> is
> > > not a bool, but rather an object definition. (It's defined in
> > > pve-access-control/src/PVE/API2/User.pm).
> > >
> > > As far as I can tell, all other 'additionalProperties' are bools. Does
> > > anyone know why this specific one is different, or if this difference
> is
> > > intentional?
> >
> > I think this was just an accident.
> >
> > > From the looks of it it seems like it's used as a "we need this
> standard
> > > option, but also have to make it optional". I am still quite new to
> perl,
> > > so I don't know if there is a way to do what was intended.
> >
> > My guess is the intent was to have
> >
> >           tokens => get_standard_option('token-info', { optional => 1 }),
> >
> > instead, @Wolfgang?
>
> The `token-info` standard option defines the structure of a single
> token, which is a hash containing `expire`, `privsep` and `comment`.
> If we map `tokens` to that, then `tokens` would be exactly one token.
>
> The returned `tokens` value is a hash mapping token names to their info,
> like:
>
>       "tokens" : {
>          "first" : {
>             "expire" : 0,
>             "privsep" : 1
>          },
>          "second" : {
>             "expire" : 0,
>             "privsep" : 1
>          }
>       }
>
> So, each value inside the `tokens` object has the `token-info` schema.
>
> Most other API calls seem to return an array with the id merged into it
> as "tokenid", but this call did it this way from the beginning...
>
> But yes, we don't *usually* do this, but our JSON schema validator
> supported this and the API call was added like this originally, so
> declaring its schema this way was easier.
>
> You can see the definition in the JSON schema spec[1]. Note that `true`
> and `false` are not explicitly mentioned there, as these values are
> themselves considered schemas that "produce themselves as assertion
> results"[2].
>
> Also note that our schema isn't fully compliant with the spec
> (for instance we declare required vs optional fields differently), but
> at least feature-wise we do try to stick to keeping it a subset of it
> (with the occasional weirdness-extension to deal with legacy cruft such
> as how you can use the *value* of the *model* property as a *key* to
> declare the mac address in a network interface for a VM's network
> device... please don't :-) )
>
> [1]
> https://json-schema.org/draft/2020-12/json-schema-core#section-10.3.2.3
> [2] https://json-schema.org/draft/2020-12/json-schema-core#section-4.3.2
>
>