1 .. SPDX-License-Identifier: GPL-2.0
2
3 Writing Devicetree Bindings in json-schema
4 ==========================================
5
6 Devicetree bindings are written using json-sch
7 written in a JSON-compatible subset of YAML. Y
8 is considered more human readable and has some
9 comments (Prefixed with '#').
10
11 Also see :ref:`example-schema`.
12
13 Schema Contents
14 ---------------
15
16 Each schema doc is a structured json-schema wh
17 top-level properties. Generally, there is one
18 top-level json-schema properties used are:
19
20 $id
21 A json-schema unique identifier string. The
22 URI typically containing the binding's filen
23 begin with "http://devicetree.org/schemas/".
24 references to other files specified in schem
25 with a leading '/' will have the hostname pr
26 relative path or filename will be prepended
27 components of the current schema file's '$id
28 local files, but there may not actually be f
29
30 $schema
31 Indicates the meta-schema the schema file ad
32
33 title
34 A one-line description of the hardware being
35
36 maintainers
37 A DT specific property. Contains a list of e
38 for maintainers of this binding.
39
40 description
41 Optional. A multi-line text block containing
42 information about this hardware. It should c
43 or device does, standards the device conform
44 more information.
45
46 select
47 Optional. A json-schema used to match nodes
48 schema. By default, without 'select', nodes
49 compatible-string values or node name. Most
50
51 allOf
52 Optional. A list of other schemas to include
53 include other schemas the binding conforms t
54 particular class of devices such as I2C or S
55
56 properties
57 A set of sub-schema defining all the DT prop
58 binding. The exact schema syntax depends on
59 common properties (e.g. 'interrupts') or are
60 properties.
61
62 A property can also define a child DT node wit
63 under it.
64
65 For more details on properties sections, see '
66
67 patternProperties
68 Optional. Similar to 'properties', but names
69
70 required
71 A list of DT properties from the 'properties
72 must always be present.
73
74 additionalProperties / unevaluatedProperties
75 Keywords controlling how schema will validat
76 schema's 'properties' or 'patternProperties'
77 have exactly one of these keywords in top-le
78 additionalProperties or unevaluatedPropertie
79 being objects, are supposed to have one as w
80
81 * additionalProperties: false
82 Most common case, where no additional sc
83 binding allows subset of properties from
84
85 * unevaluatedProperties: false
86 Used when this binding references other
87 should be allowed.
88
89 * additionalProperties: true
90 Rare case, used for schemas implementing
91 schemas are supposed to be referenced by
92 'unevaluatedProperties: false'. Typical
93
94 examples
95 Optional. A list of one or more DTS hunks im
96 Example should not contain unrelated device
97 provider binding, other nodes referenced by
98 Note: YAML doesn't allow leading tabs, so sp
99
100 Unless noted otherwise, all properties are req
101
102 Property Schema
103 ---------------
104
105 The 'properties' section of the schema contain
106 binding. Each property contains a set of const
107 vocabulary for that property. The properties s
108 validation of DT files.
109
110 For common properties, only additional constra
111 binding schema need to be defined such as how
112 possible values are valid.
113
114 Vendor-specific properties will typically need
115 exception of boolean properties, they should h
116 schemas/types.yaml. A "description" property i
117
118 The Devicetree schemas don't exactly match the
119 dtc. They are simplified to make them more com
120 boilerplate. The tools process the schema file
121 validation. There are currently 2 transformati
122
123 The default for arrays in json-schema is they
124 entries than explicitly defined. This can be r
125 'maxItems', and 'additionalItems'. However, fo
126 size is desired in most cases, so these proper
127 number of entries in an 'items' list.
128
129 The YAML Devicetree format also makes all stri
130 values a matrix (in order to define groupings)
131 is present. Single entries in schemas are fixe
132
133 Coding style
134 ------------
135
136 Use YAML coding style (two-space indentation).
137 preferred is four-space indentation.
138
139 Testing
140 -------
141
142 Dependencies
143 ~~~~~~~~~~~~
144
145 The DT schema project must be installed in ord
146 binding documents and validate DTS files using
147 project can be installed with pip::
148
149 pip3 install dtschema
150
151 Note that 'dtschema' installation requires 'sw
152 installed first. On Debian/Ubuntu systems::
153
154 apt install swig python3-dev
155
156 Several executables (dt-doc-validate, dt-mk-sc
157 installed. Ensure they are in your PATH (~/.lo
158
159 Recommended is also to install yamllint (used
160
161 Running checks
162 ~~~~~~~~~~~~~~
163
164 The DT schema binding documents must be valida
165 schema for the schema) to ensure they are both
166 binding schema. All of the DT binding document
167 ``dt_binding_check`` target::
168
169 make dt_binding_check
170
171 In order to perform validation of DT source fi
172
173 make dtbs_check
174
175 Note that ``dtbs_check`` will skip any binding
176 necessary to use ``dt_binding_check`` to get a
177 binding schema files.
178
179 It is possible to run both in a single command
180
181 make dt_binding_check dtbs_check
182
183 It is also possible to run checks with a subse
184 setting the ``DT_SCHEMA_FILES`` variable to 1
185 patterns (partial match of a fixed string). Ea
186 separated by ':'.
187
188 ::
189
190 make dt_binding_check DT_SCHEMA_FILES=triv
191 make dt_binding_check DT_SCHEMA_FILES=triv
192 make dt_binding_check DT_SCHEMA_FILES=/gpi
193 make dtbs_check DT_SCHEMA_FILES=trivial-de
194
195
196 json-schema Resources
197 ---------------------
198
199
200 `JSON-Schema Specifications <http://json-schem
201
202 `Using JSON Schema Book <http://usingjsonschem
203
204 .. _example-schema:
205
206 Annotated Example Schema
207 ------------------------
208
209 Also available as a separate file: :download:`
210
211 .. literalinclude:: example-schema.yaml
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.