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 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'. Also, probably not an issue here, but be aware that YAML is much slower to parse than JSON. > 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. > + > +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. > + 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. > + 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'. > + 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 ]'. Rob
