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
31   Indicates the meta-schema the schema file adheres to.
34   A one-line description of the hardware being described in the binding schema.
41   Optional. A multi-line text block containing any detailed
43   or device does, standards the device conforms to, and links to datasheets for
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.
57   A set of sub-schema defining all the DT properties for the
59   common properties (e.g. 'interrupts') or are binding/vendor-specific
77   have exactly one of these keywords in top-level part, so either
92       'unevaluatedProperties: false'.  Typically bus or common-part schemas.
103 ---------------
106 binding. Each property contains a set of constraints using json-schema
114 Vendor-specific properties will typically need more detailed schema. With the
118 The Devicetree schemas don't exactly match the YAML-encoded DT data produced by
123 The default for arrays in json-schema is they are variable-sized and allow more
125 'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
131 is present. Single entries in schemas are fixed up to match this encoding.
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
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