JSON Schema builder

Classes and functions to streamline JSONSchema typing.

Usage example:

jsonschema = PropertiesList(
    Property("id", IntegerType, required=True),
    Property("name", StringType),
    Property("tags", ArrayType(StringType)),
    Property("ratio", NumberType),
    Property("days_active", IntegerType),
    Property("updated_on", DateTimeType),
    Property("is_deleted", BooleanType),
    Property(
        "author",
        ObjectType(
            Property("id", StringType),
            Property("name", StringType),
        )
    ),
    Property(
        "groups",
        ArrayType(
            ObjectType(
                Property("id", StringType),
                Property("name", StringType),
            )
        )
    ),
).to_dict()

Note:

  • These helpers are designed to output json in the traditional Singer dialect.

  • Due to the expansive set of capabilities within the JSONSchema spec, there may be other valid implementations which are not syntactically identical to those generated here.

class singer_sdk.typing.ArrayType(wrapped_type: W | type[W])

Array type.

property type_dict: dict

Get type dictionary.

Returns

A dictionary describing the type.

class singer_sdk.typing.BooleanType

Boolean type.

class singer_sdk.typing.CustomType(jsonschema_type_dict: dict)

Accepts an arbitrary JSON Schema dictionary.

property type_dict: dict

Get type dictionary.

Returns

A dictionary describing the type.

class singer_sdk.typing.DateTimeType

DateTime type.

Example: 2018-11-13T20:20:39+00:00

string_format: str | None = 'date-time'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.DateType

Date type.

Example: 2018-11-13

string_format: str | None = 'date'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.DurationType

Duration type.

Example: P3D

string_format: str | None = 'duration'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.EmailType

Email type.

string_format: str | None = 'email'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.HostnameType

Hostname type.

string_format: str | None = 'hostname'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.IPv4Type

IPv4 address type.

string_format: str | None = 'ipv4'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.IPv6Type

IPv6 type.

string_format: str | None = 'ipv6'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.IntegerType

Integer type.

class singer_sdk.typing.JSONPointerType

JSONPointer type.

string_format: str | None = 'json-pointer'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.JSONTypeHelper

Type helper base class for JSONSchema types.

to_dict() dict

Convert to dictionary.

Returns

A JSON Schema dictionary describing the object.

property type_dict: dict

Return dict describing the type.

Raises

NotImplementedError – If the derived class does not override this method.

class singer_sdk.typing.NumberType

Number type.

class singer_sdk.typing.ObjectType(*properties: Property, additional_properties: W | type[W] | None = None)

Object type, which wraps one or more named properties.

property type_dict: dict

Get type dictionary.

Returns

A dictionary describing the type.

class singer_sdk.typing.PropertiesList(*properties: Property, additional_properties: W | type[W] | None = None)

Properties list. A convenience wrapper around the ObjectType class.

append(property: Property) None

Append a property to the property list.

Parameters

property – Property to add

items() list[tuple[str, Property]]

Get wrapped properties.

Returns

List of (name, property) tuples.

class singer_sdk.typing.Property(name: str, wrapped: W | type[W], required: bool = False, default: _JsonValue = None, description: str = None)

Generic Property. Should be nested within a PropertiesList.

to_dict() dict

Return a dict mapping the property name to its definition.

Returns

A JSON Schema dictionary describing the object.

property type_dict: dict

Get type dictionary.

Returns

A dictionary describing the type.

Raises

ValueError – If the type dict is not valid.

class singer_sdk.typing.RegexType

Regex type.

string_format: str | None = 'regex'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.RelativeJSONPointerType

RelativeJSONPointer type.

string_format: str | None = 'relative-json-pointer'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.StringType

String type.

string_format: str | None = None

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.TimeType

Time type.

Example: 20:20:39+00:00

string_format: str | None = 'time'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.URIReferenceType

URIReference type.

string_format: str | None = 'uri-reference'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.URITemplateType

URITemplate type.

string_format: str | None = 'uri-template'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.URIType

URI type.

string_format: str | None = 'uri'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

class singer_sdk.typing.UUIDType

UUID type.

Example: 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a

string_format: str | None = 'uuid'

String format.

See the [formats built into the JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats).

Returns

A string describing the format.

singer_sdk.typing.extend_validator_with_defaults(validator_class)

Fill in defaults, before validating with the provided JSON Schema Validator.

See https://python-jsonschema.readthedocs.io/en/latest/faq/#why-doesn-t-my-schema-s-default-property-set-the-default-on-my-instance # noqa for details.

singer_sdk.typing.to_jsonschema_type(from_type: str | sqlalchemy.types.TypeEngine | type[sqlalchemy.types.TypeEngine]) dict

Return the JSON Schema dict that describes the sql type.

Parameters

from_type – The SQL type as a string or as a TypeEngine. If a TypeEngine is provided, it may be provided as a class or a specific object instance.

Raises

ValueError – If the from_type value is not of type str or TypeEngine.

Returns

A compatible JSON Schema type definition.

singer_sdk.typing.to_sql_type(jsonschema_type: dict) TypeEngine

Convert JSON Schema type to a SQL type.

Parameters

jsonschema_type – The JSON Schema object.

Returns

The SQL type.