JSON Schema and Parsing

Orvanta leverages JSON Schema to define the structure and validation rules for JSON data, adhering to the JSON Schema standard (version 2020-12).

JSON Schema Specification

A JSON Schema defines properties, types, and constraints of a JSON object through these components:

• $schema: URL pointing to the JSON Schema specification
• type: The JSON object type (object, string, number, etc.)
• properties: Dictionary defining object properties with descriptions and types
• required: List of mandatory properties
• Additional features for validation (regex patterns, custom formats)

JSON Schema in Orvanta

Orvanta uses JSON Schema to define input specifications for scripts and flows, and to specify resource types. The schema must have properties matching declared function arguments, with support for types including: integer, number, string, boolean, object, array, and any.

Script Parameters to JSON Schema

Each parameter in a script’s main function corresponds to a field in the JSON Schema. Type mappings exist between languages and JSON Schema:

Python to JSON Schema:

• str → string
• float → number
• int → integer
• bool → boolean
• dict → object
• list → any[]
• List[str] → string[]
• bytes → string with encodingFormat: base64
• datetime → string with format: date-time

TypeScript to JSON Schema:

• string → string
• object → object
• boolean → boolean
• number → number
• string[] → string[]

TypeScript supports special Orvanta-specific types:

• orvanta.Base64 → string with encodingFormat: base64
• orvanta.Email → string with format: email
• orvanta.Sql → string with format: sql
• <ResourceType> → object with format: resource-{resource_type}

Flows Parameters and JSON Schema

Flow input parameters are defined through a JSON Schema where each “Flow Input” argument corresponds to a JSON Schema field. The schema can be modified in the Flow Input menu and viewed in the Export/OpenFlow section.

Resource Types and JSON Schema

Resource types associate with JSON Schemas to validate resource object properties against specified type constraints.

Advanced Settings

Main function arguments support advanced settings affecting auto-generated UI and JSON Schema:

Common Settings:

• Name
• Type
• Description
• Custom Title
• Placeholder
• Field settings (type-dependent)

Type-Specific Configurations:

Type	Advanced Configuration
Integer	Min/Max, Currency, Currency locale
Number	Min/Max, Currency, Currency locale
String	Textarea rows, variable picker toggle, password flag, file (base64), enum, format (email, hostname, uri, uuid, ipv4, yaml, sql, date-time), regex pattern
Boolean	None
Resource	Resource type specification
Object	Object properties or template path to JSON schema resource
Array	Item type specification (strings, enum strings, objects, numbers, bytes)
Any	None

oneOf

The oneOf type enables users to select between multiple object variants through auto-generated UI. TypeScript syntax:

example_oneof: { label: "Option 1", attribute: string } | { label: "Option 2", other_attribute: string }

The selected object is returned as the result. This works in scripts, flows, webhooks, and CLI operations.

Dynamic Select

Dynamic select creates select fields with options that recompute based on other input values.

Dynamic Select in Scripts

Export both a type as DynSelect_<name> and a function as <name>:

export type DynSelect_foo = string;
export async function foo(x: string, y: number, text: string) {
  if (text === '42') {
    return [{ value: '42', label: 'The answer to the universe' }];
  }
  return [{ value: '1', label: 'Foo' + x + y }];
}
export async function main(y: number, x: string, xy: DynSelect_foo) {
  return xy;
}

Python equivalent:

DynSelect_foo = str
def foo(x: str, y: int, text):
  if text == "42":
    return [{"value": "42", "label": "The answer to the universe"}]
  return [{"value": '1', "label": 'Foo' + x + str(y)}]

def main(x: str, y: int, xy: DynSelect_foo):
  return xy

Dynamic Select in Flows

Define one function per flow input field with dynamic select type. Function names must match the field names exactly. No export type is required.

How Dynamic Select Works

Select options recompute dynamically based on other input arguments. Custom filtering and sorting logic can be implemented within the function.

Backend Schema Validation

By default, Orvanta does not explicitly validate schemas. To enforce validation (useful for webhooks), add the schema_validation annotation as a comment at the script’s top:

// schema_validation
export async function main(
  a: number,
  b: 'my' | 'enum',
  e = 'inferred type string from default arg',
  f = { nested: 'object' },
  g:
    | { label: 'Variant 1'; foo: string; }
    | { label: 'Variant 2'; bar: number; }
) {
  return { foo: a };
}

Jobs fail if payloads don’t match the schema. Validation checks type, shape, required fields, and strict enums. Regex pattern matching on strings is not yet supported. This feature is available across all languages.