Type Reference

Riffle maps between Python type annotations and JSON Schema types. This page documents the exact mappings.

Type annotations

Python type	JSON Schema type
str	string
int	integer
float	number
bool	boolean
dict	object
list	array

Typed lists

Use bracket notation for typed arrays:

tags: list[str]       # array of strings
scores: list[int]     # array of integers
items: list[LineItem] # array of nested schema objects

Union types

When a field accepts multiple types, use the types parameter in Field():

value: str = Field(types=["string", "integer"])

The Python annotation uses str (the highest-priority type), while types preserves the full set for round-trip fidelity. Priority order: string > number > integer > boolean > array > object.

Special characters in field names

Python identifiers can’t contain hyphens, hash marks, or other special characters. Riffle translates these:

JSON field name	Python identifier	Automatic mapping
content-type	content_type	Field(name="content-type")
x-request-id	x_request_id	Field(name="x-request-id")
#calling_workflow	_calling_workflow	# prefix becomes _ prefix

Connectors

Connector steps in the function body use dot notation:

connectors.{connector_name}.{operation}(
    param=value,
)

Connector names use underscores in Python (e.g. callable_trigger) and hyphens in JSON (e.g. callable-trigger). Riffle handles the conversion automatically.

Step outputs are accessed as attributes of the variable:

query = connectors.salesforce.find_records(object="Contact")
update = connectors.salesforce.update_record(
    object_id=query.result.records.Id,
)