devicetree/bindings/writing-schema.rst

1 .. SPDX-License-Identifier: GPL-2.0
3 Writing Devicetree Bindings in json-schema
6 Devicetree bindings are written using json-schema vocabulary. Schema files are
7 written in a JSON-compatible subset of YAML. YAML is used instead of JSON as it
11 Also see :ref:`example-schema`.
14 ---------------
16 Each schema doc is a structured json-schema which is defined by a set of
17 top-level properties. Generally, there is one binding defined per file. The
18 top-level json-schema properties used are:
21   A json-schema unique identifier string. The string must be a valid
27   components of the current schema file's '$id' value. A URL is used even for
31   Indicates the meta-schema the schema file adheres to.
34   A one-line description of the hardware being described in the binding schema.
37   A DT specific property. Contains a list of email address(es)
38   for maintainers of this binding.
41   Optional. A multi-line text block containing any detailed
47   Optional. A json-schema used to match nodes for applying the
49   compatible-string values or node name. Most bindings should not need select.
52   Optional. A list of other schemas to include. This is used to
54   particular class of devices such as I2C or SPI controllers.
57   A set of sub-schema defining all the DT properties for the
59   common properties (e.g. 'interrupts') or are binding/vendor-specific
71   A list of DT properties from the 'properties' section that
77   have exactly one of these keywords in top-level part, so either
83       binding allows subset of properties from other referenced schemas.
90       Rare case, used for schemas implementing common set of properties. Such
92       'unevaluatedProperties: false'.  Typically bus or common-part schemas.
95   Optional. A list of one or more DTS hunks implementing this binding only.
103 ---------------
105 The 'properties' section of the schema contains all the DT properties for a
106 binding. Each property contains a set of constraints using json-schema
108 validation of DT files.
114 Vendor-specific properties will typically need more detailed schema. With the
115 exception of boolean properties, they should have a reference to a type in
118 The Devicetree schemas don't exactly match the YAML-encoded DT data produced by
119 dtc. They are simplified to make them more compact and avoid a bunch of
123 The default for arrays in json-schema is they are variable-sized and allow more
127 number of entries in an 'items' list.
134 ------------
136 Use YAML coding style (two-space indentation). For DTS examples in the schema,
137 preferred is four-space indentation.
140 -------
154     apt install swig python3-dev
156 Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
164 The DT schema binding documents must be validated using the meta-schema (the
165 schema for the schema) to ensure they are both valid json-schema and valid
166 binding schema. All of the DT binding documents can be validated using the
171 In order to perform validation of DT source files, use the ``dtbs_check`` target::
183 It is also possible to run checks with a subset of matching schema files by
185 patterns (partial match of a fixed string). Each file or pattern should be
190     make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml
191     make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml
193     make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml
196 json-schema Resources
197 ---------------------
200 `JSON-Schema Specifications <http://json-schema.org/>`_
204 .. _example-schema:
207 ------------------------
209 Also available as a separate file: :download:`example-schema.yaml`
211 .. literalinclude:: example-schema.yaml