Json Schema

A simple JSON schema representation to describe configs and types.

This module primarily used with Parser.to_json_schema to generate config schemas used in IDEs.

class yuio.json_schema.JsonValue

A type alias for JSON values. Can be used as type of a config field, in which case it will be parsed with the Json parser.

JSON types

class yuio.json_schema.JsonSchemaType

Base class for JSON schema representation.

precedence: ClassVar[int] = 3

Precedence, used for pretty-printing types.

abstractmethod render() → dict[str, JsonValue]

Serialize type as JSON.

remove_opaque() → JsonSchemaType | None

Return a new type with all instances of Opaque removed from it.

This is usually used before pretty-printing type for documentation.

abstractmethod pprint() → str

Pretty-print this type using TypeScript syntax.

class yuio.json_schema.Ref(ref: str, item: JsonSchemaType, name: str | None = None)

A reference to a sub-schema.

Use JsonSchemaContext.add_type() to create these.

ref: str

Referenced type.

item: JsonSchemaType

Access to the wrapped type.

name: str | None

Name of the referenced type, used for debug.

class yuio.json_schema.Array(item: JsonSchemaType, unique_items: bool = False)

An array or a set of values.

item: JsonSchemaType

Type of array elements.

unique_items: bool

Whether all array items should be unique.

class yuio.json_schema.Tuple(items: Sequence[JsonSchemaType])

A tuple.

items: Sequence[JsonSchemaType]

Types of tuple elements.

class yuio.json_schema.Dict(

key: JsonSchemaType,

value: JsonSchemaType,

)

A dict. If key is string, this is represented as an object; if key is not a string, this is represented as an array of pairs.

key: JsonSchemaType

Type of dict keys.

value: JsonSchemaType

Type of dict values.

class yuio.json_schema.Null

A null value.

class yuio.json_schema.Boolean

A boolean value.

class yuio.json_schema.Number

A numeric value.

class yuio.json_schema.Integer

An integer value.

class yuio.json_schema.String(pattern: str | None = None)

A string value, possibly with pattern.

pattern: str | None

Regular expression for checking string elements.

class yuio.json_schema.Any

A value that always type checks, equivalent to schema true.

class yuio.json_schema.Never

A value that never type checks, equivalent to schema false.

class yuio.json_schema.OneOf(items: Sequence[JsonSchemaType])

A union of possible values, equivalent to oneOf schema.

items: Sequence[JsonSchemaType]

Inner items.

class yuio.json_schema.AllOf(items: Sequence[JsonSchemaType])

An intersection of possible values, equivalent to allOf schema.

items: Sequence[JsonSchemaType]

Inner items.

class yuio.json_schema.AnyOf(items: Sequence[JsonSchemaType])

A union of possible values, equivalent to anyOf schema.

items: Sequence[JsonSchemaType]

Inner items.

class yuio.json_schema.Enum(

constants: Sequence[str | int | float | bool | None],

descriptions: Sequence[str | None] | None = None,

)

An enum of primitive constants.

constants: Sequence[str | int | float | bool | None]

Enum elements.

descriptions: Sequence[str | None] | None

Descriptions for enum items. If given, list of descriptions should have the same length as the list of constants.

class yuio.json_schema.Object(properties: dict[str, JsonSchemaType])

An object, usually represents a Config.

properties: dict[str, JsonSchemaType]

Object keys and their types.

class yuio.json_schema.Opaque(schema: dict[str, JsonValue])

Can contain arbitrary schema, for cases when these classes can’t represent required constraints.

schema: dict[str, JsonValue]

Arbitrary schema. This should be a dictionary so that Meta can add additional data to it.

class yuio.json_schema.Meta(

item: JsonSchemaType,

title: str | None = None,

description: str | None = None,

default: JsonValue | Missing = yuio.MISSING,

)

Adds title, description and defaults to the wrapped schema.

item: JsonSchemaType

Inner type.

title: str | None

Title for the wrapped item.

description: str | None

Description for the wrapped item.

default: JsonValue | yuio.Missing

Default value for the wrapped item.

Building a schema

Most likely you’ll get a schema from Config.to_json_schema or Parser.to_json_schema.

To convert it to JSON value, use JsonSchemaContext.render(), and possibly wrap the schema into Meta:

ctx = yuio.json_schema.JsonSchemaContext()
schema = yuio.json_schema.Meta(
    AppConfig.to_json_schema(ctx),
    title="Config for my application",
)
data = json.dumps(ctx.render(schema), indent=2)

class yuio.json_schema.JsonSchemaContext

Context for building schema.

add_type(

key: Any,

/,

name: str,

make_schema: Callable[[], JsonSchemaType],

) → Ref

Add a new type to the $defs section.

Parameters:

• key – a python type or object for which we’re building a schema. This type will be used as a unique key in the $defs section.

• name – name of the type, will be used in the $defs section. If there are two types with different keys and the same name, their names will be deduplicated.

• make_schema – a lambda that will be called if key wasn’t added to this context before. It should build and return the schema for this type.

Returns:

a Ref type pointing to the just-added schema.

get_type(ref: str) → JsonSchemaType | None

Get saved type by $ref.

Parameters:

ref – contents of the $ref anchor.

Returns:

schema that was earlier passed to add_type().

render(

root: JsonSchemaType,

/,

*,

id: str | None = None,

) → JsonValue

Convert schema to a value suitable for JSON serialization.

Returns:

complete JSON representation of a schema.