Re: [RFC net-next 2/4] ynl: add the schema for the schemas

[Rob Herring <robh@kernel.org>]

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@kernel.org>
> ---
>  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