At the end of the docstring, note that .. * one really should only declare default properties as required in very special cases, such as using a property as an identifier
* and that only attributes specific to PVE::JSONSchema should be declared on default properties The latter case in particular was mentioned off-list a while ago; every default property must be defined through a valid JSONSchema, any other attributes really shouldn't be added. Also correct the example in this docstring along the way, correctly quoting the key and adding `optional => 1` in order not to suggest anything that is advised against in the new paragraph further below. Signed-off-by: Max R. Carrara <[email protected]> --- src/PVE/SectionConfig.pm | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/PVE/SectionConfig.pm b/src/PVE/SectionConfig.pm index 6ad8772..71a0019 100644 --- a/src/PVE/SectionConfig.pm +++ b/src/PVE/SectionConfig.pm @@ -138,9 +138,10 @@ More precisely, this method returns a hash with the following structure: optional => 1, description => 'example property', }, - some-property => { - description => 'another example property', + 'some-property' => { type => 'boolean' + optional => 1, + description => 'another example property', }, }, options => { @@ -204,6 +205,19 @@ plugin architecture upfront, for example: Additional properties defined in I<child plugins> are stored in the C<propertyList> key. See C<L<< properties()|/$plugin->properties() >>>. +B<NOTE:> It is advised to mark all default properties in C<propertyList> as +optional using C<< optional => 1 >>, with only very few exceptions. One such +exception would be a property that you intend to use as unique identifier of a +section. In that case, ensure that you explicitly define it with +C<< optional => 0 >> and that it is not used in any child plugins' +C<L<< options()|/$plugin->options() >>> method. + +B<NOTE:> When specifying the default properties in the C<propertyList> key, you +MAY only add attributes related to C<L<PVE::JSONSchema>> to property +definitions. Any other attributes, even those specific to C<PVE::SectionConfig> +(like C<fixed>), are not considered valid. All properties in C<propertyList> +MUST be defined through a valid JSONSchema. + =cut sub private { -- 2.47.3 _______________________________________________ pve-devel mailing list [email protected] https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
