JSON Schema export for DataSet classes

This module exposes a UI-framework-agnostic representation of guidata DataSet classes as JSON Schema 2020-12 documents, augmented with x-guidata-* extension keywords for the guidata-specific concerns that JSON Schema cannot natively express (groups, tabs, units, choice labels, dynamic choices, image icons, …).

It is the non-Qt equivalent of guidata.dataset.qtwidgets: it describes the form to be rendered, leaving the actual rendering to any frontend (web, CLI, notebook, …).

Public API

guidata.dataset.jsonschema.dataset_to_schema(dataset_cls: type[DataSet]) → dict[str, Any]

Return a JSON Schema 2020-12 description of dataset_cls.

Parameters:

dataset_cls – A DataSet subclass.

Returns:

A JSON-serialisable dict that conforms to JSON Schema 2020-12 and carries guidata-specific information under x-guidata-* keys.

Raises:

• TypeError – If dataset_cls is not a DataSet subclass.

• NotImplementedError – If the class contains an item kind that is explicitly out of scope (e.g. ButtonItem).

Example

>>> import guidata.dataset as gds
>>> from guidata.dataset.jsonschema import dataset_to_schema
>>> class P(gds.DataSet):
...     '''Demo'''
...     n = gds.IntItem("Window size", default=5, min=1)
>>> schema = dataset_to_schema(P)
>>> schema["type"]
'object'
>>> schema["properties"]["n"]["minimum"]
1

guidata.dataset.jsonschema.dataset_to_schema_with_values(instance: DataSet, *, exclude_value_kinds: Collection[str] | None = None) → dict[str, Any]

Return both the schema and the current values of instance.

Parameters:

• instance – A DataSet instance.

• exclude_value_kinds – Optional x-guidata-kind values whose items remain in the schema but are omitted from the values mapping.

Returns:

{"schema": <schema>, "values": <values>} where values is a JSON-serialisable mapping of property name → value for non-group items whose kind is not excluded.

guidata.dataset.jsonschema.resolve_dynamic_choices(instance: DataSet, item_name: str) → list[dict[str, Any]]

Resolve a dynamic ChoiceItem against the current instance.

Use this helper when a property’s schema carries "x-guidata-choices-dynamic": true (and consequently no static enum). The frontend should call this whenever any value the callable depends on changes.

Parameters:

• instance – The DataSet instance providing the current state. Callers typically build a fresh instance, push the user-edited values into it via guidata.dataset.update_dataset(), then call this function.

• item_name – Name of the choice item.

Returns:

A list of {"value": <wire>, "label": <human>} dicts.

Raises:

KeyError – If item_name is not a choice item of instance.

guidata.dataset.jsonschema.resolve_dataset_callbacks(instance: DataSet, item_name: str) → dict[str, Any]

Run item_name’s display callback and return the new values.

Use this helper when a property’s schema carries "x-guidata-has-callback": true. The frontend should call it whenever that item changes, after pushing the user-edited values into a fresh instance via guidata.dataset.update_dataset() (see resolve_dynamic_choices()).

The guidata callback signature is callback(instance, item, value); it mutates instance in place (typically recomputing a read-only sibling such as ArithmeticParam.operation). This function then re-serialises every named item so the caller can refresh the whole form, mirroring the Qt update_widgets cascade.

Parameters:

• instance – The DataSet instance providing the current state. It is mutated in place by the callback.

• item_name – Name of the item whose callback to run.

Returns:

A JSON-serialisable mapping of property name → value for every non-group item, reflecting the post-callback state. Empty when the item carries no display callback.

Raises:

KeyError – If item_name is not an item of instance.

Output format

The generated dictionary is a valid JSON Schema 2020-12 object schema, with extra x-guidata-* keywords:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:guidata:dataset:my.module.MyParam",
  "title": "My parameters",
  "description": "Class docstring (excluding the title line).",
  "type": "object",
  "properties": {
    "n": {"type": "integer", "minimum": 1, "default": 5,
          "description": "Window size", "x-guidata-kind": "int",
          "x-guidata-order": 0},
    ...
  },
  "required": ["n"],
  "x-guidata-version": 1,
  "x-guidata-property-order": ["n", ...],
  "x-guidata-layout": [<layout-tree>]
}

The x-guidata-layout key is a tree of nodes:

{"kind": "group" | "tab-group" | "tab", "label": "...",
 "items": [<child-node-or-property-name>, ...]}

Leaf entries are property names (strings) that reference top-level properties keys.

Item kinds

Each property carries an x-guidata-kind keyword identifying the intended widget. Kinds emitted by this module:

int, float, bool, string, text, choice, multiple_choice, image_choice, color, date, datetime, file, float_array, dict, histogram_range.

Items not supported (raise NotImplementedError): ButtonItem (callbacks cannot cross JSON), and conditional visibility through callable active props.