# 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  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: 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: 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: 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: Sep 30, 2022