JSON Schema Helpers

Classes and functions to streamline JSONSchema typing.

Usage example:

jsonschema = PropertiesList(
    Property("username", StringType, required=True),
    Property("password", StringType, required=True, secret=True),
    Property("id", IntegerType, required=True),
    Property("foo_or_bar", StringType, allowed_values=["foo", "bar"]),
    Property(
        "permissions",
        ArrayType(
            StringType(
                allowed_values=["create", "delete", "insert", "update"],
                examples=["insert", "update"],
            ),
        ),
    ),
    Property("ratio", NumberType, examples=[0.25, 0.75, 1.0]),
    Property("days_active", IntegerType),
    Property("updated_on", DateTimeType),
    Property("is_deleted", BooleanType),
    Property(
        "author",
        ObjectType(
            Property("id", StringType),
            Property("name", StringType),
        ),
    ),
    Property("tags", ArrayType(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

Array type.

__init__(wrapped_type, **kwargs)

Initialize Array type with wrapped inner type.

Parameters:

• wrapped_type (W | type[W]) – JSON Schema item type inside the array.

• **kwargs (Any) – Additional keyword arguments to pass to the parent class.

Return type:

None

property type_dict: dict

Get type dictionary.

Returns:

A dictionary describing the type.

class singer_sdk.typing.BooleanType

Boolean type.

Examples

>>> BooleanType.type_dict
{'type': ['boolean']}
>>> BooleanType().type_dict
{'type': ['boolean']}

class singer_sdk.typing.CustomType

Accepts an arbitrary JSON Schema dictionary.

__init__(jsonschema_type_dict)

Initialize JSONTypeHelper by importing an existing JSON Schema type.

Parameters:

jsonschema_type_dict (dict) – TODO

Return type:

None

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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the built-in formats.

Returns:

A string describing the format.

class singer_sdk.typing.IntegerType

Integer type.

Examples

>>> IntegerType.type_dict
{'type': ['integer']}
>>> IntegerType().type_dict
{'type': ['integer']}
>>> IntegerType(allowed_values=[1, 2]).type_dict
{'type': ['integer'], 'enum': [1, 2]}
>>> IntegerType(minimum=0, maximum=10).type_dict
{'type': ['integer'], 'minimum': 0, 'maximum': 10}
>>> IntegerType(exclusive_minimum=0, exclusive_maximum=10).type_dict
{'type': ['integer'], 'exclusiveMinimum': 0, 'exclusiveMaximum': 10}
>>> IntegerType(multiple_of=2).type_dict
{'type': ['integer'], 'multipleOf': 2}

class singer_sdk.typing.JSONPointerType

JSONPointer type.

string_format: str | None = 'json-pointer'

String format.

See the JSON Schema reference for a list of all the built-in formats.

Returns:

A string describing the format.

class singer_sdk.typing.JSONTypeHelper

Type helper base class for JSONSchema types.

__init__(*, allowed_values=None, examples=None, nullable=None)

Initialize the type helper.

Parameters:

• allowed_values (list[T] | None) – A list of allowed values.

• examples (list[T] | None) – A list of example values.

• nullable (bool | None) – If True, the property may be null.

Return type:

None

to_dict()

Convert to dictionary.

Returns:

A JSON Schema dictionary describing the object.

Return type:

dict

to_json(**kwargs)

Convert to JSON.

Parameters:

kwargs (Any) – Additional keyword arguments to pass to json.dumps().

Returns:

A JSON string describing the object.

Return type:

str

property extras: dict

Return dict describing the JSON Schema extras.

Returns:

A dictionary containing the JSON Schema extras.

class singer_sdk.typing.NumberType

Number type.

Examples

>>> NumberType.type_dict
{'type': ['number']}
>>> NumberType().type_dict
{'type': ['number']}
>>> NumberType(allowed_values=[1.0, 2.0]).type_dict
{'type': ['number'], 'enum': [1.0, 2.0]}
>>> NumberType(minimum=0, maximum=10).type_dict
{'type': ['number'], 'minimum': 0, 'maximum': 10}
>>> NumberType(exclusive_minimum=0, exclusive_maximum=10).type_dict
{'type': ['number'], 'exclusiveMinimum': 0, 'exclusiveMaximum': 10}
>>> NumberType(multiple_of=2).type_dict
{'type': ['number'], 'multipleOf': 2}

class singer_sdk.typing.ObjectType

Object type, which wraps one or more named properties.

__init__(*properties, additional_properties=None, pattern_properties=None, **kwargs)

Initialize ObjectType from its list of properties.

Parameters:

• properties (Property) – Zero or more attributes for this JSON object.

• additional_properties (W | type[W] | bool | None) – A schema to match against unnamed properties in this object, or a boolean indicating if extra properties are allowed.

• pattern_properties (Mapping[str, W | type[W]] | None) – A dictionary of regex patterns to match against property names, and the schema to match against the values.

• **kwargs (Any) – Additional keyword arguments to pass to the JSONTypeHelper.

Return type:

None

Examples

>>> t = ObjectType(
...     Property("name", StringType, required=True),
...     Property("age", IntegerType),
...     Property("height", NumberType),
...     additional_properties=False,
... )
>>> print(t.to_json(indent=2))
{
  "type": "object",
  "properties": {
    "name": {
      "type": [
        "string"
      ]
    },
    "age": {
      "type": [
        "integer",
        "null"
      ]
    },
    "height": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
>>> t = ObjectType(
...     Property("name", StringType, required=True),
...     Property("age", IntegerType),
...     Property("height", NumberType),
...     additional_properties=StringType,
... )
>>> print(t.to_json(indent=2))
{
  "type": "object",
  "properties": {
    "name": {
      "type": [
        "string"
      ]
    },
    "age": {
      "type": [
        "integer",
        "null"
      ]
    },
    "height": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": {
    "type": [
      "string"
    ]
  }
}

property type_dict: dict

Get type dictionary.

Returns:

A dictionary describing the type.

class singer_sdk.typing.PropertiesList

Properties list. A convenience wrapper around the ObjectType class.

Examples

>>> schema = PropertiesList(
...     # username/password
...     Property("username", StringType, requires_properties=["password"]),
...     Property("password", StringType, secret=True),
...     # OAuth
...     Property(
...         "client_id",
...         StringType,
...         requires_properties=["client_secret", "refresh_token"],
...     ),
...     Property("client_secret", StringType, secret=True),
...     Property("refresh_token", StringType, secret=True),
... )
>>> print(schema.to_json(indent=2))
{
  "type": "object",
  "properties": {
    "username": {
      "type": [
        "string",
        "null"
      ]
    },
    "password": {
      "type": [
        "string",
        "null"
      ],
      "secret": true,
      "writeOnly": true
    },
    "client_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "client_secret": {
      "type": [
        "string",
        "null"
      ],
      "secret": true,
      "writeOnly": true
    },
    "refresh_token": {
      "type": [
        "string",
        "null"
      ],
      "secret": true,
      "writeOnly": true
    }
  },
  "dependentRequired": {
    "username": [
      "password"
    ],
    "client_id": [
      "client_secret",
      "refresh_token"
    ]
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

append(property)

Append a property to the property list.

Parameters:

property (Property) – Property to add

Return type:

None

items()

Get wrapped properties.

Returns:

List of (name, property) tuples.

Return type:

ItemsView[str, Property]

property type_dict: dict

Get type dictionary.

Returns:

A dictionary describing the type.

class singer_sdk.typing.Property

Generic Property. Should be nested within a PropertiesList.

__init__(name, wrapped, required=False, default=None, description=None, secret=False, allowed_values=None, examples=None, *, nullable=None, title=None, deprecated=None, requires_properties=None, **kwargs)

Initialize Property object.

Note: Properties containing secrets should be specified with secret=True. Doing so will add the annotation writeOnly=True, in accordance with JSON Schema Draft 7 and later, and secret=True as an additional hint to readers.

More info: https://json-schema.org/draft-07/json-schema-release-notes.html

Parameters:

• name (str) – Property name.

• wrapped (JSONTypeHelper[T] | type[JSONTypeHelper[T]]) – JSON Schema type of the property.

• required (bool) – Whether this is a required property.

• default (T | None) – Default value in the JSON Schema.

• description (str | None) – Long-text property description.

• secret (bool | None) – True if this is a credential or other secret.

• allowed_values (list[T] | None) – A list of allowed value options, if only specific values are permitted. This will define the type as an ‘enum’.

• examples (list[T] | None) – Optional. A list of one or more sample values. These may be displayed to the user as hints of the expected format of inputs.

• nullable (bool | None) – If True, the property may be null.

• title (str | None) – Optional. A short, human-readable title for the property.

• deprecated (bool | None) – If True, mark this property as deprecated.

• requires_properties (list[str] | None) – A list of property names that must also be present if this property is present.

• **kwargs (Any) – Additional keyword arguments to pass to the parent class.

Return type:

None

to_dict()

Return a dict mapping the property name to its definition.

Returns:

A JSON Schema dictionary describing the object.

Return type:

dict

Examples

>>> p = Property("name", StringType, required=True)
>>> print(p.to_dict())
{'name': {'type': ['string']}}
>>> p = Property("name", StringType, required=True, title="App Name")
>>> print(p.to_dict())
{'name': {'type': ['string'], 'title': 'App Name'}}

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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the built-in formats.

Returns:

A string describing the format.

class singer_sdk.typing.StringType

String type.

Examples

>>> StringType.type_dict
{'type': ['string']}
>>> StringType().type_dict
{'type': ['string']}
>>> StringType(allowed_values=["a", "b"]).type_dict
{'type': ['string'], 'enum': ['a', 'b']}
>>> StringType(max_length=10).type_dict
{'type': ['string'], 'maxLength': 10}
>>> StringType(max_length=10, nullable=True).type_dict
{'type': ['string', 'null'], 'maxLength': 10}

__init__(*, min_length=None, max_length=None, pattern=None, **kwargs)

Initialize StringType.

Parameters:

• min_length (int | None) – Minimum length of the string. See the JSON Schema reference for details.

• max_length (int | None) – Maximum length of the string. See the JSON Schema reference for details.

• pattern (str | None) – A regular expression pattern that the string must match. See the JSON Schema reference for details.

• **kwargs (Any) – Additional keyword arguments to pass to the parent class.

Return type:

None

string_format: str | None = None

String format.

See the JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 JSON Schema reference for a list of all the 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 for details.

Parameters:

validator_class (type[Validator]) – The JSON Schema Validator class to extend.

Returns:

The extended JSON Schema Validator class.

singer_sdk.typing.to_jsonschema_type(from_type)

Return the JSON Schema dict that describes the sql type.

Parameters:

from_type (str | TypeEngine | type[TypeEngine]) – 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.

Return type:

dict

singer_sdk.typing.to_sql_type(jsonschema_type)

Convert JSON Schema type to a SQL type.

Parameters:

jsonschema_type (dict) – The JSON Schema object.

Returns:

The SQL type.

Return type:

TypeEngine