Re: [PATCH pve-common v4 01/17] json schema: add multiline string format

["Max R. Carrara" <m.carrara@proxmox.com>]

On Tue Nov 10, 2026 at 2:39 PM CET, Wolfgang Bumiller wrote:
> Given that right now, newlines are almost never wanted/allowed in our
> API (apart from comments), there's a case to be made here that we might
> just want a multiline schema flag. (Where by default we'd reject
> newlines. This could potentially remove a whole class of possible future
> section-config related bugs…)

If a fear of SectionConfig bugs is preventing us from simply adding
multiline strings, we should seriously consider migrating the
SectionConfig *file format* to something different in the long term.

>
> Also, consider that on the rust side, 'format', 'enum', 'pattern', and
> the verify-functions are part of the `ApiStringFormat` *enum*, so you
> can only have one, [...]

Which is something we should change eventually then, since validation
keywords are independent unless explicitly stated otherwise, at least as
per section 3.1.1 of this draft:

https://json-schema.org/draft-07/draft-handrews-json-schema-validation-00.pdf

Sure, you could argue that it doesn't make sense to have `format`,
`enum`, and `pattern` co-exist for the same property, but the spec
doesn't place any restrictions on this.


> [...] and we do not have *named* formats at all.

Why not?

>
> Thomas also played around with the thought of adding a multiline boolean
> to string schemas, so this may be a good time to come to a decision
> here.
>
> IMO, while not strictly being part of any JSONSchema/openapi spec, it
> would be fine to have that. Also, I'm quite sure that whenever we use
> patterns or other formats, a pattern which does not want to opt into
> multiline support should be written in a way which does not allow
> newlines *anyway*, so for the most part it would act as a hint, but
> additionally provide a safe-guard just in case.

NAK -- I don't think we should deviate from the spec just to make a
multiline string format work. The `format` key handles it already, and
any frontend helpers that convert the schema of a property to UI
elements can check for this format and adjust the element's type
accordingly.

This is already what this series does, and unless I have missed
something, works just fine without any additional contortions.

The exception here is that SectionConfig, due to how its file format is
designed, does not allow reading / writing multiline strings, which
means that properties with `format => 'multiline'` would have to be
handled as a special case. We already do this for many other properties
in `encode_value` / `decode_value` anyway -- and in the case of the
`multiline` format, the call site can opt to reading from / writing to a
file for that particular property.

>
> On Fri, Nov 06, 2026 at 04:45:37PM +0100, Max R. Carrara wrote:
> > Add a new format named "multiline".
> >
> > This format explicitly signals to other components (e.g. a client)
> > that a string is a multiline string and should remain one, without
> > folding newlines or replacing them with spaces, for example.
> >
> > Signed-off-by: Max R. Carrara <m.carrara@proxmox.com>
> > ---
> >  src/PVE/JSONSchema.pm | 5 +++++
> >  1 file changed, 5 insertions(+)
> >
> > diff --git a/src/PVE/JSONSchema.pm b/src/PVE/JSONSchema.pm
> > index 34f2949..5790a32 100644
> > --- a/src/PVE/JSONSchema.pm
> > +++ b/src/PVE/JSONSchema.pm
> > @@ -236,10 +236,15 @@ sub get_renderer {
> >
> >  # register some common type for pve
> >
> >  register_format('string', sub { }); # allow format => 'string-list'
> >
> > +# A multiline string.
> > +# Used to explicitly tell other components that a string should not
> > +# have its newlines folded or replaced with spaces.
> > +register_format('multiline', sub { });
> > +
> >  register_format('urlencoded', \&pve_verify_urlencoded);
> >
> >  sub pve_verify_urlencoded {
> >      my ($text, $noerr) = @_;
> >      if ($text !~ /^[-%a-zA-Z0-9_.!~*'()]*\z/) {
> > --
> > 2.47.3