Fixing up non-standard schema with DT tooling (was "Re: [PATCH] dt-bindings: Drop redundant minItems/maxItems")

Hi Rob,

I am splitting this message out as a separate thread because the 
original one Cced lots of people and lists mainly because it touched 
lots of subsystems. This discussion is more focussed on device tree side 
of things.

On 15/06/21 01:15PM, Rob Herring wrote:

If a property has an 'items' list, then a 'minItems' or 'maxItems' with the
same size as the list is redundant and can be dropped. Note that is DT
schema specific behavior and not standard json-schema behavior. The tooling
will fixup the final schema adding any unspecified minItems/maxItems.

Please understand that things like this have a hidden cost involved.

For example, I was thoroughly confused a couple weeks back when I was 
looking at the binding for spi/cdns,qspi-nor.yaml. It has 4 properties 
for the subnode: 'cdns,read-delay', 'cdns,tshsl-ns', 'cdns,tsd2d-ns', 
and 'cdns,tslch-ns'. The latter three are fine with just a description 
and need nothing else to define their types. The first one needs a $ref 
to uint32. I could not figure out why. I even looked at the processed 
JSON schema and came out none the wiser.

After banging my head on the table for some time, I finally came across 
the dt-schema repo's property-units.yaml file which makes every property 
ending in "-ns" a uint32-array.

This is a neat feature and makes writing bindings slightly easier if you 
know about it. But it makes reading bindings a very difficult process if 
you don't know about it. The same applies to every little thing that the 
tooling does in the background in the name of convenience.

You are very familiar with the entire ecosystem so these things are 
obvious for you. They aren't as obvious for most other developers who 
don't deal with bindings or yaml or JSON schema on a regular basis. I 
don't know enough about the ecosystem to prescribe whether this or some 
other hidden behaviour is good or not. But I want you to keep this in 
mind. The more things tooling does in the background, the more things 
the average developer needs to know, and the harder it becomes to read 
and write bindings.

This condition is partially checked with the meta-schema already, but
only if both 'minItems' and 'maxItems' are equal to the 'items' length.
An improved meta-schema is pending.

-- 
Regards,
Pratyush Yadav
Texas Instruments Inc.