docs: writing-schema.md: convert from markdown to ReST

# Writing DeviceTree Bindings in json-schema

:orphan:

Writing DeviceTree Bindings in json-schema

==========================================

Devicetree bindings are written using json-schema vocabulary. Schema files are

written in a JSON compatible subset of YAML. YAML is used instead of JSON as it

considered more human readable and has some advantages such as allowing

comments (Prefixed with '#').

## Schema Contents

Schema Contents

---------------

Each schema doc is a structured json-schema which is defined by a set of

top-level properties. Generally, there is one binding defined per file. The

top-level json-schema properties used are:

- __$id__ - A json-schema unique identifier string. The string must be a valid

$id

  A json-schema unique identifier string. The string must be a valid

  URI typically containing the binding's filename and path. For DT schema, it must

  begin with "http://devicetree.org/schemas/". The URL is used in constructing

  references to other files specified in schema "$ref" properties. A $ref values

  of the current schema file's '$id' value. A URL is used even for local files,

  but there may not actually be files present at those locations.

- __$schema__ - Indicates the meta-schema the schema file adheres to.

$schema

  Indicates the meta-schema the schema file adheres to.

- __title__ - A one line description on the contents of the binding schema.

title

  A one line description on the contents of the binding schema.

- __maintainers__ - A DT specific property. Contains a list of email address(es)

maintainers

  A DT specific property. Contains a list of email address(es)

  for maintainers of this binding.

- __description__ - Optional. A multi-line text block containing any detailed

description

  Optional. A multi-line text block containing any detailed

  information about this binding. It should contain things such as what the block

  or device does, standards the device conforms to, and links to datasheets for

  more information.

- __select__ - Optional. A json-schema used to match nodes for applying the

select

  Optional. A json-schema used to match nodes for applying the

  schema. By default without 'select', nodes are matched against their possible

  compatible string values or node name. Most bindings should not need select.

- __allOf__ - Optional. A list of other schemas to include. This is used to

 allOf

  Optional. A list of other schemas to include. This is used to

  include other schemas the binding conforms to. This may be schemas for a

  particular class of devices such as I2C or SPI controllers.

- __properties__ - A set of sub-schema defining all the DT properties for the

 properties

  A set of sub-schema defining all the DT properties for the

  binding. The exact schema syntax depends on whether properties are known,

  common properties (e.g. 'interrupts') or are binding/vendor specific properties.

For more details on properties sections, see 'Property Schema' section.

- __patternProperties__ - Optional. Similar to 'properties', but names are regex.

patternProperties

  Optional. Similar to 'properties', but names are regex.

- __required__ - A list of DT properties from the 'properties' section that

required

  A list of DT properties from the 'properties' section that

  must always be present.

- __examples__ - Optional. A list of one or more DTS hunks implementing the

examples

  Optional. A list of one or more DTS hunks implementing the

  binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.

Unless noted otherwise, all properties are required.

## Property Schema

Property Schema

---------------

The 'properties' section of the schema contains all the DT properties for a

binding. Each property contains a set of constraints using json-schema

values a matrix (in order to define groupings) even when only a single value

is present. Single entries in schemas are fixed up to match this encoding.

## Testing

Testing

-------

### Dependencies

Dependencies

~~~~~~~~~~~~

The DT schema project must be installed in order to validate the DT schema

binding documents and validate DTS files using the DT schema. The DT schema

project can be installed with pip:

project can be installed with pip::

`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`

    pip3 install git+https://github.com/devicetree-org/dt-schema.git@master

dtc must also be built with YAML output support enabled. This requires that

libyaml and its headers be installed on the host system.

### Running checks

Running checks

~~~~~~~~~~~~~~

The DT schema binding documents must be validated using the meta-schema (the

schema for the schema) to ensure they are both valid json-schema and valid

binding schema. All of the DT binding documents can be validated using the

`dt_binding_check` target:

``dt_binding_check`` target::

`make dt_binding_check`

    make dt_binding_check

In order to perform validation of DT source files, use the `dtbs_check` target:

In order to perform validation of DT source files, use the `dtbs_check` target::

`make dtbs_check`

    make dtbs_check

This will first run the `dt_binding_check` which generates the processed schema.

It is also possible to run checks with a single schema file by setting the

'DT_SCHEMA_FILES' variable to a specific schema file.

``DT_SCHEMA_FILES`` variable to a specific schema file.

::

    make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml

`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`

json-schema Resources

---------------------

## json-schema Resources

[JSON-Schema Specifications](http://json-schema.org/)

`JSON-Schema Specifications <http://json-schema.org/>`_

[Using JSON Schema Book](http://usingjsonschema.com/)

`Using JSON Schema Book <http://usingjsonschema.com/>`_