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:

quoted

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.

quoted

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.

Ack!

quoted

+
+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/
 

quoted

+    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.

quoted

+  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.

quoted

+  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!