[PATCH] docs: dt: writing-schema: Describe defining properties in top-level

[PATCH] docs: dt: writing-schema: Describe defining properties in top-level

[Krzysztof Kozlowski]

Document established Devicetree bindings maintainers review practice:
Properties having differences per each device in the binding, e.g.
different constraints for lists or different allowed values, should
still be defined in top-level 'properties' section and only customized
in 'if:then:'.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 Documentation/devicetree/bindings/writing-schema.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index 470d1521fa17..e0859094575d 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -165,6 +165,14 @@ The YAML Devicetree format also makes all string values an array and scalar
 values a matrix (in order to define groupings) even when only a single value
 is present. Single entries in schemas are fixed up to match this encoding.
 
+When bindings cover multiple similar devices that differ in some properties,
+those properties should be constrained for each device. This usually means:
+
+ * In top level 'properties' define the property with the broadest constraints.
+ * In 'if:then:' blocks, further narrow the constraints for those properties.
+ * Do not define the properties within an 'if:then:' block (note that
+   'additionalItems' also won't allow that).
+
 Coding style
 ------------
 
-- 
2.48.1

Re: [PATCH] docs: dt: writing-schema: Describe defining properties in top-level

[Frank Li]

On Thu, Sep 04, 2025 at 04:24:01PM +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> Properties having differences per each device in the binding, e.g.
> different constraints for lists or different allowed values, should
> still be defined in top-level 'properties' section and only customized
> in 'if:then:'.

'customized' is not easy understand in my view.

only restrict (such as limit number of item, limit data range, disabllow
properties) in 'if: then:' section.

>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  Documentation/devicetree/bindings/writing-schema.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
> index 470d1521fa17..e0859094575d 100644
> --- a/Documentation/devicetree/bindings/writing-schema.rst
> +++ b/Documentation/devicetree/bindings/writing-schema.rst
> @@ -165,6 +165,14 @@ The YAML Devicetree format also makes all string values an array and scalar
>  values a matrix (in order to define groupings) even when only a single value
>  is present. Single entries in schemas are fixed up to match this encoding.
>
> +When bindings cover multiple similar devices that differ in some properties,
> +those properties should be constrained for each device. This usually means:
> +
> + * In top level 'properties' define the property with the broadest constraints.
> + * In 'if:then:' blocks, further narrow the constraints for those properties.
> + * Do not define the properties within an 'if:then:' block (note that
> +   'additionalItems' also won't allow that).
> +

I can understand what your said. I think it would be better if add some
simple examples.

Frank

>  Coding style
>  ------------
>
> --
> 2.48.1
>

Re: [PATCH] docs: dt: writing-schema: Describe defining properties in top-level

[Krzysztof Kozlowski]

On 04/09/2025 17:30, Frank Li wrote:
>> diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
>> index 470d1521fa17..e0859094575d 100644
>> --- a/Documentation/devicetree/bindings/writing-schema.rst
>> +++ b/Documentation/devicetree/bindings/writing-schema.rst
>> @@ -165,6 +165,14 @@ The YAML Devicetree format also makes all string values an array and scalar
>>  values a matrix (in order to define groupings) even when only a single value
>>  is present. Single entries in schemas are fixed up to match this encoding.
>>
>> +When bindings cover multiple similar devices that differ in some properties,
>> +those properties should be constrained for each device. This usually means:
>> +
>> + * In top level 'properties' define the property with the broadest constraints.
>> + * In 'if:then:' blocks, further narrow the constraints for those properties.
>> + * Do not define the properties within an 'if:then:' block (note that
>> +   'additionalItems' also won't allow that).
>> +
> 
> I can understand what your said. I think it would be better if add some
> simple examples.
Example for that is already there - at the bottom of this file.

Best regards,
Krzysztof

Re: [PATCH] docs: dt: writing-schema: Describe defining properties in top-level

[Frank Li]

On Fri, Sep 05, 2025 at 08:49:01AM +0200, Krzysztof Kozlowski wrote:
> On 04/09/2025 17:30, Frank Li wrote:
> >> diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
> >> index 470d1521fa17..e0859094575d 100644
> >> --- a/Documentation/devicetree/bindings/writing-schema.rst
> >> +++ b/Documentation/devicetree/bindings/writing-schema.rst
> >> @@ -165,6 +165,14 @@ The YAML Devicetree format also makes all string values an array and scalar
> >>  values a matrix (in order to define groupings) even when only a single value
> >>  is present. Single entries in schemas are fixed up to match this encoding.
> >>
> >> +When bindings cover multiple similar devices that differ in some properties,
> >> +those properties should be constrained for each device. This usually means:
> >> +
> >> + * In top level 'properties' define the property with the broadest constraints.
> >> + * In 'if:then:' blocks, further narrow the constraints for those properties.
> >> + * Do not define the properties within an 'if:then:' block (note that
> >> +   'additionalItems' also won't allow that).
> >> +
> >
> > I can understand what your said. I think it would be better if add some
> > simple examples.
> Example for that is already there - at the bottom of this file.

example-schema.yaml is big, it is hard to match to this specific rule. some
small section will be helpful

              properties:
                a:               # define 'a' at top
                  enum: [0, 1]   # width range in here
              allOf:
                - if:
                    ...          # some condition
                  then:
                    properties:
                      a:
                        const: 0 # allow only 0 for some specific condition.

Frank


>
> Best regards,
> Krzysztof

Re: [PATCH] docs: dt: writing-schema: Describe defining properties in top-level

[Rob Herring (Arm)]

On Thu, 04 Sep 2025 16:24:01 +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> Properties having differences per each device in the binding, e.g.
> different constraints for lists or different allowed values, should
> still be defined in top-level 'properties' section and only customized
> in 'if:then:'.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  Documentation/devicetree/bindings/writing-schema.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 

Applied, thanks!