JSON domain

This theme defines a json domain that supports documenting JSON schemas.

Prerequisite

This extension requires the PyYAML package; you must either add it as a dependency directly, or add json extra feature of this package as a dependency:

pip install sphinx-immaterial[json]

Configuration

To use this domain, add sphinx_immaterial.apidoc.json.domain to the list of extensions in conf.py and set the json_schemas configuration option to a list of glob patterns specifying the JSON schema definition files.

extensions = [
    # other extensions...
    "sphinx_immaterial.apidoc.json.domain",
]

json_schemas = [
    "**/*_schema.yml",
]
json_schemas : list[str] = []

List of glob patterns matching JSON schema definition files relative to the documentation source directory.

Both JSON and YAML format are supported.

The top-level schema in each file must specify an $id.

json_schema_validate : bool = False

Indicates whether to validate the JSON schemas specified by json_schemas.

Requires that the jsonschema package is installed; you can either add it as a dependency directly, or depend on the jsonschema_validation extra feature of this package:

pip install sphinx-immaterial[json,jsonschema_validation]
json_schema_rst_prolog : str = ''

A string of rST that will be prepended to the title and description fields of a schema before parsing them as rST.

This may be used to set the rST directive default-role, highlight language, or default-literal-role.

Note

The prior default role, default literal role, and default highlight langauge are automatically restored after processing the json_schema_rst_epilog. Therefore, it is not necessary to manually add anything to json_schema_rst_epilog to restore the prior roles or highlight language.

Setting default roles and highlight language in conf.py
rst_prolog = """
.. role:: json(code)
   :language: json
   :class: highlight
"""

json_schema_rst_prolog = """
.. default-role:: json:schema

.. default-literal-role:: json

.. highlight:: json
"""
json_schema_rst_epilog : str = ''

A string of rST that will be appended to the title and description fields of a schema before parsing them as rST.

This option is supported for symmetry with json_schema_rst_prolog, but in most cases is not needed because any changes to the default role, default literal role, and default highlight language due to json_schema_rst_prolog are undone automatically.

All of the Object description options also apply to this domain. Any top-level schemas have an object type of json:schema and any members have an object type of json:subschema.

Usage

.. json:schema::

Generates documentation for a single JSON schema specified by its $id.

Note

It is not possible to refer to a schema without an $id.

The title and description properties are parsed as reStructedText (in the context specified by json_schema_rst_prolog and json_schema_rst_epilog).

If generate_synopses is not disabled, the synopsis is generated from the title property. If there is no title property, no synopsis is generated.

:noindex:

Flag option to exclude the schema from search results and the table of contents. Also disables cross linking.

This option implies json:schema:exclude_from_toc.

:title:

Specifies a title to use for the schema instead of the $id.

:toc_title:

Specifies the title to use in the table of contents instead of the json:schema:title or $id.

Only has an effect if include_in_toc is True.

:exclude_from_toc:

Excludes the schema from the table of contents.

This overrides include_in_toc.

:json:schema:

Cross-links to a JSON schema defined using json:schema, or one of its properties.

A complete schema is specified by its ``$id``: :json:schema:`Pet`.

An individual member of a schema is specified using dot notation:
:json:schema:`Pet.name`.

A complete schema is specified by its $id: Pet.

An individual member of a schema is specified using dot notation: Pet.name.

Similar to the Python domain, the target may start with ~ to shorten the link text to just the last component:

:json:schema:`~Pet.name`

name

If used within the title or description of a json:schema, cross-references are resolved relative to the current schema. For example, within the “description” for the MySchema.member schema:

:json:schema:`.other_member`

will look first for MySchema.member.other_member, then MySchema.other_member, then other_member. This is the same behavior as for the Python domain. If the initial . is removed, then search order is reversed. For example: :json:schema:`other_member` will look first for other_member, then MySchema.other_member, then MySchema.member.other_member.

Examples

Inheritance example

inheritance_schema.yml
$schema: http://json-schema.org/draft-07/schema#
$id: Pet
title: "Represents a generic pet."
type: object
properties:
  type:
    type: string
    title: Type of pet.
  name:
    type: string
    title: Name of the pet.
  age:
    type: number
    title: Age of the pet in years.
    minimum: 0
required:
- type
- name

definitions:
  dog:
    $id: Dog
    title: "Represents a dog."
    allOf:
    - $ref: Pet
    - type: object
      properties:
        type:
          const: "dog"
        bark_volume:
          type: number
          title: "Bark volume in dB."
        favorite_walk:
          type: string
          title: "Favorite place to walk."
  cat:
    $id: Cat
    title: "Represents a cat."
    allOf:
    - $ref: Pet
    - type: object
      properties:
        type:
          const: "cat"
        meow_volume:
          type: number
          title: "Meow volume in dB."
        favorite_scratching_post:
          type: string
          title: "Favorite place to scratch."
    examples:
    - {"type": "cat", "name": "Tom", "age": 10, "meow_volume": 45}

.. json:schema:: Pet
.. json:schema:: Dog
.. json:schema:: Cat
json Pet : object

Represents a generic pet.

Subtypes:

  • Cat — Represents a cat.

  • Dog — Represents a dog.

Required members:
type : string

Type of pet.

name : string

Name of the pet.

Optional members:
age : number[0, +∞)

Age of the pet in years.

json Dog : object

Represents a dog.

Extends:

  • Pet — Represents a generic pet.

Required members:
type : "dog"
name : string

Name of the pet.

Optional members:
age : number[0, +∞)

Age of the pet in years.

bark_volume : number

Bark volume in dB.

favorite_walk : string

Favorite place to walk.

json Cat : object

Represents a cat.

Extends:

  • Pet — Represents a generic pet.

Required members:
type : "cat"
name : string

Name of the pet.

Optional members:
age : number[0, +∞)

Age of the pet in years.

meow_volume : number

Meow volume in dB.

favorite_scratching_post : string

Favorite place to scratch.

Example

{"type": "cat", "name": "Tom", "age": 10, "meow_volume": 45}

Other example

index_transform_schema.yml
$schema: http://json-schema.org/draft-07/schema#
$id: IndexTransform
description: |
  Index transforms may be serialized to/from JSON using
  the following schema.

  The input domain is specified by `.input_rank`,
  `.input_inclusive_min`, `.input_exclusive_max`,
  `.input_inclusive_max`, `.input_shape`, and
  `.input_labels`, while the output index maps are specified by
  `.output`.

  If neither `.input_inclusive_min` nor `.input_shape`
  is specified, all dimensions receive an implicit lower bound of
  :math:`-\infty`.  If `.input_shape` is specified but
  `.input_inclusive_min` is not specified, all dimensions receive an
  explicit lower bound of 0.

  At most one of `.input_exclusive_max`,
  `.input_inclusive_max`, and `.input_shape` may be
  specified.  If none are specified, all dimensions receive an implicit upper
  bound of :math:`+\infty`.

type: object
properties:
  input_rank:
    type: integer
    minimum: 0
    maximum: 32
    title: Number of input dimensions.
    description: |
      The input rank must be specified either directly, or implicitly by the
      number of dimensions specified for `.input_inclusive_min`,
      `.input_inclusive_max`, `.input_exclusive_max`,
      `.input_shape`, or `.input_labels`.
  input_inclusive_min:
    type: array
    items:
      oneOf:
        - type: integer
        - type: array
          items:
            - type: integer
    title: |
      Inclusive lower bounds of the input domain.
    description: |
      Length must equal the `.input_rank`.  Bounds specified as :samp:`{n}`
      indicate normal, explicit bounds, while bounds specified as :samp:`[{n}]`
      indicate implicit bounds.  For example, :json:`[1, [2]]` specifies an
      explicit bound of :math:`1 \leq x` for the first dimension and an implicit
      bound of :math:`2 \leq x` for the second dimension.
  input_exclusive_max:
    type: array
    items:
      oneOf:
        - type: integer
        - type: array
          items:
            - type: integer
    title: |
      Exclusive upper bounds of the input domain.
    description: |
      Length must equal the `.input_rank`.  As for `.input_inclusive_min`,
      bounds specified as :samp:`{n}` indicate normal, explicit bounds, while
      bounds specified as :samp:`[{n}]` indicate implicit bounds.  For example,
      :json:`[5, [7]]` specifies an explicit bound of :math:`x < 5` for the
      first dimension and an implicit bound of :math:`x < 7` for the second
      dimension.
  input_inclusive_max:
    type: array
    items:
      oneOf:
        - type: integer
        - type: array
          items:
            - type: integer
    title: |
      Inclusive upper bounds of the input domain.
    description: |
      Length must equal the `.input_rank`.  As for `.input_inclusive_min`,
      bounds specified as :samp:`{n}` indicate normal, explicit bounds, while
      bounds specified as :samp:`[{n}]` indicate implicit bounds.  For example,
      :json:`[5, [7]]` specifies an explicit bound of :math:`x \leq 5` for the
      first dimension and an implicit bound of :math:`x \leq 7` for the second
      dimension.
  input_shape:
    type: array
    items:
      oneOf:
        - type: integer
        - type: array
          items:
            - type: integer
    title: |
      Extent of each dimension of the input domain.
    description: |
      Length must equal the `.input_rank`.  As for `.input_inclusive_min`,
      bounds specified as :samp:`{n}` indicate normal, explicit bounds, while
      bounds specified as :samp:`[{n}]` indicate implicit bounds.  For example,
      assuming an `.input_inclusive_min` of :json:`[1, 2]`, an `.input_shape` of
      :json:`[5, [7]]` specifies an explicit bound of :math:`x < 6` for the
      first dimension and an implicit bound of :math:`x < 9` for the second
      dimension.
  input_labels:
    type: array
    items:
      type: string
    title: |
      Dimension labels for each input domain dimension.
    description: |
      Length must equal the `.input_rank`.  An empty string
      indicates an unlabeled dimension.  Non-empty strings must not occur more
      than once.  By default, all dimensions are unlabeled.
  output:
    type: array
    title: |
      Specifies the output index map for each output dimension.
    description: |
      If not specified, defaults to an identity transform over the input domain.
      Otherwise, the length determines the output rank of the transform.
    items:
      $ref: OutputIndexMap
definitions:
  output-index-map:
    $id: OutputIndexMap
    title: Specifies a transform from an input space to a single output index.
    description: |
      Logically, an output index map is a function that maps ``n``-dimensional
      input index vectors to a single output index, using one of the supported
      output index methods.  This is used to represent the
      :json:schema:`IndexTransform.output` mapping for each output dimension of
      an `IndexTransform`.
    type: object
    properties:
      offset:
        type: integer
        title: |
          Specifies an offset for this output dimension.  If neither
          `.input_dimension` nor `.index_array` is
          specified, this specifies the **constant** value to which this output
          dimension maps.
      stride:
        type: integer
        title: |
          Multiplier for the input index specified by
          `.input_dimension` or the index array value specified by
          `.index_array`.
        description: |
          Only valid to specify in conjunction with
          `.input_dimension` or `.index_array`.
      input_dimension:
        type: integer
        minimum: 0
        title: |
          If present, indicates that this output dimension uses a **single
          input dimension** map with the specified input dimension.  Must not
          be specified in conjunction with `.index_array`.
      index_array:
        oneOf:
          - type: array
          - type: integer
        title: |
          If present, indicates that this output dimension uses an **index
          array** map, with the index array specified as a nested list of rank
          equal to the `~IndexTransform.input_rank`.
        description: |
          If the `~IndexTransform.input_rank` is 0, must be a numeric value.
      index_array_bounds:
        $ref: IndexInterval
        description: |
          If present, specifies constraints on the values within
          `.index_array` (which must also be specified).  If
          `.index_array` contains an out-of-bounds index, an error
          may not be returned immediately but will be returned if the
          corresponding position within the domain is accessed.  If the
          indices in `.index_array` have already been validated,
          this need not be specified.  This allows transforms containing
          out-of-bounds index array indices to correctly round trip through
          JSON, but normally need not be specified manually.
        default: ["-inf", "+inf"]
        examples:
          - [5, 100]
          - ["-inf", 10]
          - [-20, "+inf"]
  index-interval:
    $id: IndexInterval
    title: Specifies a closed interval of integer index values.
    type: array
    items:
      - oneOf:
          - type: integer
          - const: "-inf"
      - oneOf:
          - type: integer
          - const: "+inf"

.. json:schema:: IndexTransform
.. json:schema:: OutputIndexMap
.. json:schema:: IndexInterval
json IndexTransform : object

Index transforms may be serialized to/from JSON using the following schema.

The input domain is specified by input_rank, input_inclusive_min, input_exclusive_max, input_inclusive_max, input_shape, and input_labels, while the output index maps are specified by output.

If neither input_inclusive_min nor input_shape is specified, all dimensions receive an implicit lower bound of \(-\infty\). If input_shape is specified but input_inclusive_min is not specified, all dimensions receive an explicit lower bound of 0.

At most one of input_exclusive_max, input_inclusive_max, and input_shape may be specified. If none are specified, all dimensions receive an implicit upper bound of \(+\infty\).

Optional members:
input_rank : integer[0, 32]

Number of input dimensions.

The input rank must be specified either directly, or implicitly by the number of dimensions specified for input_inclusive_min, input_inclusive_max, input_exclusive_max, input_shape, or input_labels.

input_inclusive_min : array of integer | [integer]

Inclusive lower bounds of the input domain.

Length must equal the input_rank. Bounds specified as n indicate normal, explicit bounds, while bounds specified as [n] indicate implicit bounds. For example, [1, [2]] specifies an explicit bound of \(1 \leq x\) for the first dimension and an implicit bound of \(2 \leq x\) for the second dimension.

input_exclusive_max : array of integer | [integer]

Exclusive upper bounds of the input domain.

Length must equal the input_rank. As for input_inclusive_min, bounds specified as n indicate normal, explicit bounds, while bounds specified as [n] indicate implicit bounds. For example, [5, [7]] specifies an explicit bound of \(x < 5\) for the first dimension and an implicit bound of \(x < 7\) for the second dimension.

input_inclusive_max : array of integer | [integer]

Inclusive upper bounds of the input domain.

Length must equal the input_rank. As for input_inclusive_min, bounds specified as n indicate normal, explicit bounds, while bounds specified as [n] indicate implicit bounds. For example, [5, [7]] specifies an explicit bound of \(x \leq 5\) for the first dimension and an implicit bound of \(x \leq 7\) for the second dimension.

input_shape : array of integer | [integer]

Extent of each dimension of the input domain.

Length must equal the input_rank. As for input_inclusive_min, bounds specified as n indicate normal, explicit bounds, while bounds specified as [n] indicate implicit bounds. For example, assuming an input_inclusive_min of [1, 2], an input_shape of [5, [7]] specifies an explicit bound of \(x < 6\) for the first dimension and an implicit bound of \(x < 9\) for the second dimension.

input_labels : array of string

Dimension labels for each input domain dimension.

Length must equal the input_rank. An empty string indicates an unlabeled dimension. Non-empty strings must not occur more than once. By default, all dimensions are unlabeled.

output : array of OutputIndexMap

Specifies the output index map for each output dimension.

If not specified, defaults to an identity transform over the input domain. Otherwise, the length determines the output rank of the transform.

json OutputIndexMap : object

Specifies a transform from an input space to a single output index.

Logically, an output index map is a function that maps n-dimensional input index vectors to a single output index, using one of the supported output index methods. This is used to represent the IndexTransform.output mapping for each output dimension of an IndexTransform.

Optional members:
offset : integer

Specifies an offset for this output dimension. If neither input_dimension nor index_array is specified, this specifies the constant value to which this output dimension maps.

stride : integer

Multiplier for the input index specified by input_dimension or the index array value specified by index_array.

Only valid to specify in conjunction with input_dimension or index_array.

input_dimension : integer[0, +∞)

If present, indicates that this output dimension uses a single input dimension map with the specified input dimension. Must not be specified in conjunction with index_array.

index_array : array | integer

If present, indicates that this output dimension uses an index array map, with the index array specified as a nested list of rank equal to the input_rank.

If the input_rank is 0, must be a numeric value.

index_array_bounds : IndexInterval = ["-inf", "+inf"]

If present, specifies constraints on the values within index_array (which must also be specified). If index_array contains an out-of-bounds index, an error may not be returned immediately but will be returned if the corresponding position within the domain is accessed. If the indices in index_array have already been validated, this need not be specified. This allows transforms containing out-of-bounds index array indices to correctly round trip through JSON, but normally need not be specified manually.

Example

[5, 100]

Example

["-inf", 10]

Example

[-20, "+inf"]
json IndexInterval : [integer | "-inf", integer | "+inf"]

Specifies a closed interval of integer index values.

Last update: Dec 16, 2024