JSON Schema builder

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("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: W | type[W]) None

Initialize Array type with wrapped inner type.

Parameters

wrapped_type – JSON Schema item type inside the array.

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

Accepts an arbitrary JSON Schema dictionary.

__init__(jsonschema_type_dict: dict) None

Initialize JSONTypeHelper by importing an existing JSON Schema type.

Parameters

jsonschema_type_dict – TODO

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.

to_json(**kwargs: Any) str

Convert to JSON.

Parameters

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

Returns

A JSON string 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

Object type, which wraps one or more named properties.

__init__(*properties: Property, additional_properties: W | type[W] | bool | None = None, pattern_properties: Mapping[str, W | type[W]] | None = None) None

Initialize ObjectType from its list of properties.

Parameters
  • properties – Zero or more attributes for this JSON object.

  • additional_properties – A schema to match against unnamed properties in this object, or a boolean indicating if extra properties are allowed.

  • pattern_properties – A dictionary of regex patterns to match against property names, and the schema to match against the values.

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.

append(property: Property) None

Append a property to the property list.

Parameters

property – Property to add

items() ItemsView[str, Property]

Get wrapped properties.

Returns

List of (name, property) tuples.

class singer_sdk.typing.Property

Generic Property. Should be nested within a PropertiesList.

__init__(name: str, wrapped: W | type[W], required: bool = False, default: _JsonValue | None = None, description: str | None = None, secret: bool | None = False, allowed_values: list[Any] | None = None, examples: list[Any] | None = None) None

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 – Property name.

  • wrapped – JSON Schema type of the property.

  • required – Whether this is a required property.

  • default – Default value in the JSON Schema.

  • description – Long-text property description.

  • secret – True if this is a credential or other secret.

  • allowed_values – A list of allowed value options, if only specific values are permitted. This will define the type as an ‘enum’.

  • examples – Optional. A list of one or more sample values. These may be displayed to the user as hints of the expected format of inputs.

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.