On Mon, 26 Sep 2022 11:10:56 -0500 Rob Herring wrote: > On Wed, Aug 10, 2022 at 07:23:02PM -0700, Jakub Kicinski wrote: > > A schema in jsonschema format which should be familiar > > to dt-bindings writers. It looks kinda hard to read, TBH, > > I'm not sure how to make it better. > > This got my attention in the Plumbers agenda though I missed the talk. > It's nice to see another jsonschema user in the kernel. I hope you make > jsonschema a dependency for everyone before I do. :) Hopefully we don't > hit any comflict in required version of jsonschema as I've needed both a > minimum version for features as well as been broken by new versions. I'm a complete noob on this, my jsonschema is really crude. But thanks to this it's unlikely to depend on any particular version? :) > I would avoid calling all this 'YAML netlink' as YAML is just the file > format you are using. We started with calling things YAML, but I nudge > folks away from that to 'DT schema'. Good point, I'll try to stick to Netlink schema as well. > Also, probably not an issue here, but be aware that YAML is much > slower to parse than JSON. Fingers crossed. Worst case we can convert formats later. > > Signed-off-by: Jakub Kicinski <kuba@xxxxxxxxxx> > > --- > > Documentation/netlink/schema.yaml | 242 ++++++++++++++++++++++++++++++ > > 1 file changed, 242 insertions(+) > > create mode 100644 Documentation/netlink/schema.yaml > > > > diff --git a/Documentation/netlink/schema.yaml b/Documentation/netlink/schema.yaml > > new file mode 100644 > > index 000000000000..1290aa4794ba > > --- /dev/null > > +++ b/Documentation/netlink/schema.yaml > > @@ -0,0 +1,242 @@ > > +# SPDX-License-Identifier: GPL-2.0 > > +%YAML 1.2 > > +--- > > +$id: "http://kernel.org/schemas/netlink/schema.yaml#"; > > +$schema: "http://kernel.org/meta-schemas/core.yaml#"; > > In case there's ever another one: meta-schemas/netlink/core.yaml > > Or something similar. Ack! > > + > > +title: Protocol > > +description: Specification of a genetlink protocol > > +type: object > > +required: [ name, description, attribute-spaces, operations ] > > +additionalProperties: False > > +properties: > > + name: > > + description: Name of the genetlink family > > + type: string > > + description: > > It's better if your schema vocabulary is disjoint from jsonschema > vocabulary. From what I've seen, it's fairly common to get the > indentation off and jsonschema behavior is to ignore unknown keywords. > If the vocabularies are disjoint, you can write a meta-schema that only > allows jsonschema schema vocabulary at the right levels. Probably less > of an issue here as you don't have 1000s of schemas. Ack, let me s/decription/doc/ > > + description: Description of the family > > + type: string > > + version: > > + description: Version of the family as defined by genetlink. > > + type: integer > > Do you have the need to define the int size? We did our own keyword for > this, but since then I've looked at several other projects that have > used something like 'format: uint32'. There was some chatter about > trying to standardize this, but I haven't checked in a while. It's 8 bits in theory (struct genlmsghdr::version), in practice it's never used, and pretty much ignored. The jsonschema I have on Fedora does not know about uint8. > > + attr-cnt-suffix: > > + description: Suffix for last member of attribute enum, default is "MAX". > > + type: string > > + headers: > > + description: C headers defining the protocol > > + type: object > > + additionalProperties: False > > + properties: > > + uapi: > > + description: Path under include/uapi where protocol definition is placed > > + type: string > > + kernel: > > + description: Additional headers on which the protocol definition depends (kernel side) > > + anyOf: &str-or-arrstr > > + - > > + type: array > > + items: > > + type: string > > + - > > + type: string > > + user: > > + description: Additional headers on which the protocol definition depends (user side) > > + anyOf: *str-or-arrstr > > For DT, we stick to a JSON compatible subset of YAML, so no anchors. The > jsonschema way to do this is using '$defs' (or 'definitions' before the > spec standardized it) and '$ref'. I need to read up on this. Is it possible to extend a type? We really need a way to define a narrow set of properties for "going forward" while the old families have extra quirks. I couldn't find any jsonschema docs on how the inherit and extend. > > + constants: > > + description: Enums and defines of the protocol > > + type: array > > + items: > > + type: object > > + required: [ type, name ] > > + additionalProperties: False > > + properties: > > + name: > > + type: string > > + type: > > + enum: [ enum, flags ] > > + value-prefix: > > + description: For enum the prefix of the values, optional. > > + type: string > > + value-start: > > + description: For enum the literal initializer for the first value. > > + oneOf: [ { type: string }, { type: integer }] > > I think you can do just 'type: [ string, integer ]'. Works, thanks!
