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: Union[W, type[W]], **kwargs: Any) None
Initialize Array type with wrapped inner type.
- Parameters:
wrapped_type – JSON Schema item type inside the array.
**kwargs – Additional keyword arguments to pass to the parent class.
- 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: 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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]}
- class singer_sdk.typing.JSONPointerType
JSONPointer type.
- string_format: str | None = 'json-pointer'
String format.
See the formats built into the JSON Schema specification.
- Returns:
A string describing the format.
- class singer_sdk.typing.JSONTypeHelper
Type helper base class for JSONSchema types.
- __init__(*, allowed_values: list[T] | None = None, examples: list[T] | None = None) None
Initialize the type helper.
- Parameters:
allowed_values – A list of allowed values.
examples – A list of example values.
- property extras: dict
Return dict describing the JSON Schema extras.
- Returns:
A dictionary containing the JSON Schema extras.
- 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.
- 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]}
- class singer_sdk.typing.ObjectType
Object type, which wraps one or more named properties.
- __init__(*properties: Property, additional_properties: Optional[Union[W, type[W], bool]] = None, pattern_properties: Optional[Mapping[str, Union[W, type[W]]]] = None, **kwargs: Any) 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.
**kwargs – Additional keyword arguments to pass to the JSONTypeHelper.
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: Union[JSONTypeHelper[T], type[singer_sdk.typing.JSONTypeHelper[T]]], required: bool = False, default: Optional[T] = None, description: str | None = None, secret: bool | None = False, allowed_values: list[T] | None = None, examples: list[T] | 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.
- 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.
- 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']}
- string_format: str | None = None
String format.
See the formats built into the JSON Schema specification.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 – The JSON Schema Validator class to extend.
- Returns:
The extended JSON Schema Validator class.
- singer_sdk.typing.to_jsonschema_type(from_type: str | sqlalchemy.sql.type_api.TypeEngine | type[sqlalchemy.sql.type_api.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.