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[source]

Array type.

__init__(wrapped_type, **kwargs)[source]

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[source]

Get type dictionary.

Returns:

A dictionary describing the type.

class singer_sdk.typing.BooleanType[source]

Boolean type.

Examples

>>> BooleanType.type_dict
{'type': ['boolean']}
>>> BooleanType().type_dict
{'type': ['boolean']}
class singer_sdk.typing.CustomType[source]

Accepts an arbitrary JSON Schema dictionary.

__init__(jsonschema_type_dict)[source]

Initialize JSONTypeHelper by importing an existing JSON Schema type.

Parameters:

jsonschema_type_dict (dict) – TODO

Return type:

None

property type_dict: dict[source]

Get type dictionary.

Returns:

A dictionary describing the type.

class singer_sdk.typing.DateTimeType[source]

DateTime type.

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

string_format: str | None = 'date-time'[source]

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[source]

Date type.

Example: 2018-11-13

string_format: str | None = 'date'[source]

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[source]

Duration type.

Example: P3D

string_format: str | None = 'duration'[source]

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[source]

Email type.

string_format: str | None = 'email'[source]

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[source]

Hostname type.

string_format: str | None = 'hostname'[source]

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[source]

IPv4 address type.

string_format: str | None = 'ipv4'[source]

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[source]

IPv6 type.

string_format: str | None = 'ipv6'[source]

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[source]

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[source]

JSONPointer type.

string_format: str | None = 'json-pointer'[source]

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[source]

Type helper base class for JSONSchema types.

__init__(*, allowed_values=None, examples=None, nullable=None)[source]

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()[source]

Convert to dictionary.

Returns:

A JSON Schema dictionary describing the object.

Return type:

dict

to_json(**kwargs)[source]

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[source]

Return dict describing the JSON Schema extras.

Returns:

A dictionary containing the JSON Schema extras.

class singer_sdk.typing.NumberType[source]

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[source]

Object type, which wraps one or more named properties.

__init__(*properties, additional_properties=None, pattern_properties=None, **kwargs)[source]

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[source]

Get type dictionary.

Returns:

A dictionary describing the type.

class singer_sdk.typing.PropertiesList[source]

Properties list. A convenience wrapper around the ObjectType class.

append(property)[source]

Append a property to the property list.

Parameters:

property (Property) – Property to add

Return type:

None

items()[source]

Get wrapped properties.

Returns:

List of (name, property) tuples.

Return type:

ItemsView[str, Property]

class singer_sdk.typing.Property[source]

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)[source]

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.

Return type:

None

to_dict()[source]

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[source]

Get type dictionary.

Returns:

A dictionary describing the type.

Raises:

ValueError – If the type dict is not valid.

class singer_sdk.typing.RegexType[source]

Regex type.

string_format: str | None = 'regex'[source]

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[source]

RelativeJSONPointer type.

string_format: str | None = 'relative-json-pointer'[source]

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[source]

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)[source]

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[source]

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[source]

Time type.

Example: 20:20:39+00:00

string_format: str | None = 'time'[source]

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[source]

URIReference type.

string_format: str | None = 'uri-reference'[source]

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[source]

URITemplate type.

string_format: str | None = 'uri-template'[source]

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[source]

URI type.

string_format: str | None = 'uri'[source]

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[source]

UUID type.

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

string_format: str | None = 'uuid'[source]

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)[source]

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)[source]

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)[source]

Convert JSON Schema type to a SQL type.

Parameters:

jsonschema_type (dict) – The JSON Schema object.

Returns:

The SQL type.

Return type:

TypeEngine