xref: /linux/Documentation/devicetree/bindings/writing-schema.rst (revision ec16a3cdf37e507013062f9c4a2067eacdd12b62)
1.. SPDX-License-Identifier: GPL-2.0
2
3Writing Devicetree Bindings in json-schema
4==========================================
5
6Devicetree bindings are written using json-schema vocabulary. Schema files are
7written in a JSON-compatible subset of YAML. YAML is used instead of JSON as it
8is considered more human readable and has some advantages such as allowing
9comments (Prefixed with '#').
10
11Also see :ref:`example-schema`.
12
13Schema Contents
14---------------
15
16Each schema doc is a structured json-schema which is defined by a set of
17top-level properties. Generally, there is one binding defined per file. The
18top-level json-schema properties used are:
19
20$id
21  A json-schema unique identifier string. The string must be a valid
22  URI typically containing the binding's filename and path. For DT schema, it must
23  begin with "http://devicetree.org/schemas/". The URL is used in constructing
24  references to other files specified in schema "$ref" properties. A $ref value
25  with a leading '/' will have the hostname prepended. A $ref value with only a
26  relative path or filename will be prepended with the hostname and path
27  components of the current schema file's '$id' value. A URL is used even for
28  local files, but there may not actually be files present at those locations.
29
30$schema
31  Indicates the meta-schema the schema file adheres to.
32
33title
34  A one-line description of the hardware being described in the binding schema.
35
36maintainers
37  A DT specific property. Contains a list of email address(es)
38  for maintainers of this binding.
39
40description
41  Optional. A multi-line text block containing any detailed
42  information about this hardware. It should contain things such as what the block
43  or device does, standards the device conforms to, and links to datasheets for
44  more information.
45
46  The YAML format has several options for defining the formatting of the text
47  block. The options are controlled with indicator characters following the key
48  (e.g. "description: \|"). The minimum formatting needed for a block should be
49  used. The formatting controls can not only affect whether the YAML can be
50  parsed correctly, but are important when the text blocks are rendered to
51  another form. The options are as follows.
52
53  The default without any indicators is flowed, plain scalar style where single
54  line breaks and leading whitespace are stripped. Paragraphs are delimited by
55  blank lines (i.e. double line break). This style cannot contain ": " in it as
56  it will be interpretted as a key. Any " #" sequence will be interpretted as
57  a comment. There's other restrictions on characters as well. Most
58  restrictions are on what the first character can be.
59
60  The second style is folded which is indicated by ">" character. In addition
61  to maintaining line breaks on double line breaks, the folded style also
62  maintains leading whitespace beyond indentation of the first line. The line
63  breaks on indented lines are also maintained.
64
65  The third style is literal which is indicated by "\|" character. The literal
66  style maintains all line breaks and whitespace (beyond indentation of the
67  first line).
68
69  The above is not a complete description of YAML text blocks. More details on
70  multi-line YAML text blocks can be found online:
71
72  https://yaml-multiline.info/
73
74  https://www.yaml.info/learn/quote.html
75
76select
77  Optional. A json-schema used to match nodes for applying the
78  schema. By default, without 'select', nodes are matched against their possible
79  compatible-string values or node name. Most bindings should not need select.
80
81allOf
82  Optional. A list of other schemas to include. This is used to
83  include other schemas the binding conforms to. This may be schemas for a
84  particular class of devices such as I2C or SPI controllers.
85
86properties
87  A set of sub-schema defining all the DT properties for the
88  binding. The exact schema syntax depends on whether properties are known,
89  common properties (e.g. 'interrupts') or are binding/vendor-specific
90  properties.
91
92A property can also define a child DT node with child properties defined
93under it.
94
95For more details on properties sections, see 'Property Schema' section.
96
97patternProperties
98  Optional. Similar to 'properties', but names are regex.
99
100required
101  A list of DT properties from the 'properties' section that
102  must always be present.
103
104additionalProperties / unevaluatedProperties
105  Keywords controlling how schema will validate properties not matched by this
106  schema's 'properties' or 'patternProperties'. Each schema is supposed to
107  have exactly one of these keywords in top-level part, so either
108  additionalProperties or unevaluatedProperties. Nested nodes, so properties
109  being objects, are supposed to have one as well.
110
111  * additionalProperties: false
112      Most common case, where no additional schema is referenced or if this
113      binding allows subset of properties from other referenced schemas.
114
115  * unevaluatedProperties: false
116      Used when this binding references other schema whose all properties
117      should be allowed.
118
119  * additionalProperties: true
120      Rare case, used for schemas implementing common set of properties. Such
121      schemas are supposed to be referenced by other schemas, which then use
122      'unevaluatedProperties: false'.  Typically bus or common-part schemas.
123
124examples
125  Optional. A list of one or more DTS hunks implementing this binding only.
126  Example should not contain unrelated device nodes, e.g. consumer nodes in a
127  provider binding, other nodes referenced by phandle.
128  Note: YAML doesn't allow leading tabs, so spaces must be used instead.
129
130Unless noted otherwise, all properties are required.
131
132Property Schema
133---------------
134
135The 'properties' section of the schema contains all the DT properties for a
136binding. Each property contains a set of constraints using json-schema
137vocabulary for that property. The properties schemas are what are used for
138validation of DT files.
139
140For common properties, only additional constraints not covered by the common,
141binding schema need to be defined such as how many values are valid or what
142possible values are valid.
143
144Vendor-specific properties will typically need more detailed schema. With the
145exception of boolean properties, they should have a reference to a type in
146schemas/types.yaml. A "description" property is always required.
147
148The Devicetree schemas don't exactly match the YAML-encoded DT data produced by
149dtc. They are simplified to make them more compact and avoid a bunch of
150boilerplate. The tools process the schema files to produce the final schema for
151validation. There are currently 2 transformations the tools perform.
152
153The default for arrays in json-schema is they are variable-sized and allow more
154entries than explicitly defined. This can be restricted by defining 'minItems',
155'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
156size is desired in most cases, so these properties are added based on the
157number of entries in an 'items' list.
158
159The YAML Devicetree format also makes all string values an array and scalar
160values a matrix (in order to define groupings) even when only a single value
161is present. Single entries in schemas are fixed up to match this encoding.
162
163Coding style
164------------
165
166Use YAML coding style (two-space indentation). For DTS examples in the schema,
167preferred is four-space indentation.
168
169Testing
170-------
171
172Dependencies
173~~~~~~~~~~~~
174
175The DT schema project must be installed in order to validate the DT schema
176binding documents and validate DTS files using the DT schema. The DT schema
177project can be installed with pip::
178
179    pip3 install dtschema
180
181Note that 'dtschema' installation requires 'swig' and Python development files
182installed first. On Debian/Ubuntu systems::
183
184    apt install swig python3-dev
185
186Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
187installed. Ensure they are in your PATH (~/.local/bin by default).
188
189Recommended is also to install yamllint (used by dtschema when present).
190
191Running checks
192~~~~~~~~~~~~~~
193
194The DT schema binding documents must be validated using the meta-schema (the
195schema for the schema) to ensure they are both valid json-schema and valid
196binding schema. All of the DT binding documents can be validated using the
197``dt_binding_check`` target::
198
199    make dt_binding_check
200
201In order to perform validation of DT source files, use the ``dtbs_check`` target::
202
203    make dtbs_check
204
205Note that ``dtbs_check`` will skip any binding schema files with errors. It is
206necessary to use ``dt_binding_check`` to get all the validation errors in the
207binding schema files.
208
209It is possible to run both in a single command::
210
211    make dt_binding_check dtbs_check
212
213It is also possible to run checks with a subset of matching schema files by
214setting the ``DT_SCHEMA_FILES`` variable to 1 or more specific schema files or
215patterns (partial match of a fixed string). Each file or pattern should be
216separated by ':'.
217
218::
219
220    make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml
221    make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml
222    make dt_binding_check DT_SCHEMA_FILES=/gpio/
223    make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml
224
225
226json-schema Resources
227---------------------
228
229
230`JSON-Schema Specifications <http://json-schema.org/>`_
231
232`Using JSON Schema Book <http://usingjsonschema.com/>`_
233
234.. _example-schema:
235
236Annotated Example Schema
237------------------------
238
239Also available as a separate file: :download:`example-schema.yaml`
240
241.. literalinclude:: example-schema.yaml
242