[PATCH] dt-bindings: example: Extend based on practice

[PATCH] dt-bindings: example: Extend based on practice

[Krzysztof Kozlowski]

Extend the example schema with common rules which seems to be not that
obvious:
1. Expecting arrays of phandles to be always ordered, regardless if
   "xxx-names" is provided (e.g. clocks),
2. Add example of altering a property based on presence of other
   property,
3. Document usage of unevaluatedProperties.

Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
---
 .../devicetree/bindings/example-schema.yaml   | 33 ++++++++++++++-----
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml
index 822975dbeafa..b381db1ae00a 100644
--- a/Documentation/devicetree/bindings/example-schema.yaml
+++ b/Documentation/devicetree/bindings/example-schema.yaml
@@ -81,6 +81,8 @@ properties:
     maxItems: 1
     description: bus clock. A description is only needed for a single item if
       there's something unique to add.
+      The items should be have a fixed order, so pattern matching names are
+      discouraged.
 
   clock-names:
     items:
@@ -97,6 +99,8 @@ properties:
       A variable number of interrupts warrants a description of what conditions
       affect the number of interrupts. Otherwise, descriptions on standard
       properties are not necessary.
+      The items should be have a fixed order, so pattern matching names are
+      discouraged.
 
   interrupt-names:
     # minItems must be specified here because the default would be 2
@@ -196,14 +200,24 @@ required:
 #
 # If the conditionals become too unweldy, then it may be better to just split
 # the binding into separate schema documents.
-if:
-  properties:
-    compatible:
-      contains:
-        const: vendor,soc2-ip
-then:
-  required:
-    - foo-supply
+allOf:
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: vendor,soc2-ip
+    then:
+      required:
+        - foo-supply
+  # Altering schema depending on presence of properties is usually done by
+  # dependencies (see above), however some adjustments might require if:
+  - if:
+      required:
+        - vendor,bool-property
+    then:
+      properties:
+        vendor,int-property:
+          enum: [2, 4, 6]
 
 # Ideally, the schema should have this line otherwise any other properties
 # present are allowed. There's a few common properties such as 'status' and
@@ -211,6 +225,9 @@ then:
 #
 # This can't be used in cases where another schema is referenced
 # (i.e. allOf: [{$ref: ...}]).
+# If and only if another schema is referenced and arbitrary children nodes can
+# appear, "unevaluatedProperties: false" could be used.  Typical example is I2C
+# controller where no name pattern matching for childre can be added.
 additionalProperties: false
 
 examples:
-- 
2.17.1

Re: [PATCH] dt-bindings: example: Extend based on practice

[Rob Herring]

On Thu, 10 Sep 2020 20:47:06 +0200, Krzysztof Kozlowski wrote:
> Extend the example schema with common rules which seems to be not that
> obvious:
> 1. Expecting arrays of phandles to be always ordered, regardless if
>    "xxx-names" is provided (e.g. clocks),
> 2. Add example of altering a property based on presence of other
>    property,
> 3. Document usage of unevaluatedProperties.
> 
> Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
> ---
>  .../devicetree/bindings/example-schema.yaml   | 33 ++++++++++++++-----
>  1 file changed, 25 insertions(+), 8 deletions(-)
> 

Applied, thanks!

I keep meaning to go work on improving this...