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 on the contents of 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
81 ---------------
84 binding. Each property contains a set of constraints using json-schema
92 Vendor-specific properties will typically need more detailed schema. With the
96 The Devicetree schemas don't exactly match the YAML-encoded DT data produced by
101 The default for arrays in json-schema is they are variable-sized and allow more
103 'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
109 is present. Single entries in schemas are fixed up to match this encoding.
112 ------------
114 Use YAML coding style (two-space indentation). For DTS examples in the schema,
115 preferred is four-space indentation.
118 -------
132     apt install swig python3-dev
134 Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
142 The DT schema binding documents must be validated using the meta-schema (the
143 schema for the schema) to ensure they are both valid json-schema and valid
166     make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml
168     make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml
171 json-schema Resources
172 ---------------------
175 `JSON-Schema Specifications <http://json-schema.org/>`_
179 .. _example-schema:
182 ------------------------
184 Also available as a separate file: :download:`example-schema.yaml`
186 .. literalinclude:: example-schema.yaml