Documentation/devicetree/writing-schema.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Writing DeviceTree Bindings in json-schema
   4 ==========================================
   5
   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
   8 is considered more human readable and has some advantages such as allowing
   9 comments (Prefixed with '#').
  10
  11 Schema Contents
  12 ---------------
  13
  14 Each schema doc is a structured json-schema which is defined by a set of
  15 top-level properties. Generally, there is one binding defined per file. The
  16 top-level json-schema properties used are:
  17
  18 $id
  19   A json-schema unique identifier string. The string must be a valid
  20   URI typically containing the binding's filename and path. For DT schema, it must
  21   begin with "http://devicetree.org/schemas/". The URL is used in constructing
  22   references to other files specified in schema "$ref" properties. A $ref value
  23   with a leading '/' will have the hostname prepended. A $ref value a relative
  24   path or filename only will be prepended with the hostname and path components
  25   of the current schema file's '$id' value. A URL is used even for local files,
  26   but there may not actually be files present at those locations.
  27
  28 $schema
  29   Indicates the meta-schema the schema file adheres to.
  30
  31 title
  32   A one line description on the contents of the binding schema.
  33
  34 maintainers
  35   A DT specific property. Contains a list of email address(es)
  36   for maintainers of this binding.
  37
  38 description
  39   Optional. A multi-line text block containing any detailed
  40   information about this binding. It should contain things such as what the block
  41   or device does, standards the device conforms to, and links to datasheets for
  42   more information.
  43
  44 select
  45   Optional. A json-schema used to match nodes for applying the
  46   schema. By default without 'select', nodes are matched against their possible
  47   compatible string values or node name. Most bindings should not need select.
  48
  49  allOf
  50   Optional. A list of other schemas to include. This is used to
  51   include other schemas the binding conforms to. This may be schemas for a
  52   particular class of devices such as I2C or SPI controllers.
  53
  54  properties
  55   A set of sub-schema defining all the DT properties for the
  56   binding. The exact schema syntax depends on whether properties are known,
  57   common properties (e.g. 'interrupts') or are binding/vendor specific properties.
  58
  59 A property can also define a child DT node with child properties defined
  60 under it.
  61
  62 For more details on properties sections, see 'Property Schema' section.
  63
  64 patternProperties
  65   Optional. Similar to 'properties', but names are regex.
  66
  67 required
  68   A list of DT properties from the 'properties' section that
  69   must always be present.
  70
  71 examples
  72   Optional. A list of one or more DTS hunks implementing the
  73   binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
  74
  75 Unless noted otherwise, all properties are required.
  76
  77 Property Schema
  78 ---------------
  79
  80 The 'properties' section of the schema contains all the DT properties for a
  81 binding. Each property contains a set of constraints using json-schema
  82 vocabulary for that property. The properties schemas are what is used for
  83 validation of DT files.
  84
  85 For common properties, only additional constraints not covered by the common
  86 binding schema need to be defined such as how many values are valid or what
  87 possible values are valid.
  88
  89 Vendor specific properties will typically need more detailed schema. With the
  90 exception of boolean properties, they should have a reference to a type in
  91 schemas/types.yaml. A "description" property is always required.
  92
  93 The Devicetree schemas don't exactly match the YAML encoded DT data produced by
  94 dtc. They are simplified to make them more compact and avoid a bunch of
  95 boilerplate. The tools process the schema files to produce the final schema for
  96 validation. There are currently 2 transformations the tools perform.
  97
  98 The default for arrays in json-schema is they are variable sized and allow more
  99 entries than explicitly defined. This can be restricted by defining 'minItems',
 100 'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
 101 size is desired in most cases, so these properties are added based on the
 102 number of entries in an 'items' list.
 103
 104 The YAML Devicetree format also makes all string values an array and scalar
 105 values a matrix (in order to define groupings) even when only a single value
 106 is present. Single entries in schemas are fixed up to match this encoding.
 107
 108 Testing
 109 -------
 110
 111 Dependencies
 112 ~~~~~~~~~~~~
 113
 114 The DT schema project must be installed in order to validate the DT schema
 115 binding documents and validate DTS files using the DT schema. The DT schema
 116 project can be installed with pip::
 117
 118     pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
 119
 120 Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
 121 installed. Ensure they are in your PATH (~/.local/bin by default).
 122
 123 dtc must also be built with YAML output support enabled. This requires that
 124 libyaml and its headers be installed on the host system. For some distributions
 125 that involves installing the development package, such as:
 126
 127 Debian::
 128
 129   apt-get install libyaml-dev
 130
 131 Fedora::
 132
 133   dnf -y install libyaml-devel
 134
 135 Running checks
 136 ~~~~~~~~~~~~~~
 137
 138 The DT schema binding documents must be validated using the meta-schema (the
 139 schema for the schema) to ensure they are both valid json-schema and valid
 140 binding schema. All of the DT binding documents can be validated using the
 141 ``dt_binding_check`` target::
 142
 143     make dt_binding_check
 144
 145 In order to perform validation of DT source files, use the ``dtbs_check`` target::
 146
 147     make dtbs_check
 148
 149 Note that ``dtbs_check`` will skip any binding schema files with errors. It is
 150 necessary to use ``dt_binding_check`` to get all the validation errors in the
 151 binding schema files.
 152
 153 It is possible to run both in a single command::
 154
 155     make dt_binding_check dtbs_check
 156
 157 It is also possible to run checks with a single schema file by setting the
 158 ``DT_SCHEMA_FILES`` variable to a specific schema file.
 159
 160 ::
 161
 162     make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
 163     make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
 164
 165
 166 json-schema Resources
 167 ---------------------
 168
 169
 170 `JSON-Schema Specifications <http://json-schema.org/>`_
 171
 172 `Using JSON Schema Book <http://usingjsonschema.com/>`_