Defined Output Schemas

A connector can pass the provider’s response through as-is, or map it onto an output schema you define so every provider in a category returns the same shape. That mapping is where most of the work goes, and where most of the mistakes are.

Mapping to your schema

Two step functions do the work, both documented in full on Step Functions:

Step function	Role
`map_fields`	Maps provider fields onto your `targetFieldKey` names, including enum translation via `enumMapper`
`typecast`	Runs after `map_fields` to coerce the mapped values to their declared types

Use version: "2" for both map_fields and typecast.

Give the agent your target schema

Your target schema is the thing you’d otherwise restate for every provider you map, so write it down where the agent can read it:

---
name: Employee Sync Schema
description: Target schema for employee data synchronization
---

# Employee Sync Schema

## Target schema

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| id | string | yes | Unique identifier |
| email | string | yes | Primary email |
| first_name | string | yes | |
| last_name | string | yes | |
| status | enum | yes | Values: active, inactive, terminated |
| department | string | no | |
| hire_date | datetime_string | no | ISO 8601 format |

## Enum mappings

### status

| Provider value | Schema value |
|----------------|--------------|
| Active, active, ACTIVE | active |
| Inactive, inactive, INACTIVE | inactive |
| Terminated, terminated, TERMINATED | terminated |
| * (default) | unknown |

With that in place, the agent maps a new provider’s employee response to your schema without being asked, including the enum normalization that is easy to get subtly wrong by hand.

Checklist

Before publishing a connector with a defined output schema, verify:

Schema definition

Target schema documented before building
All required fields identified
Field types specified (string, number, enum, datetime_string)
Enum values defined with mappings

Field mapping

fieldConfigs map all schema fields
targetFieldKey uses your schema names, not the provider’s
Nested paths verified against the actual response
Enum mappings handle every provider value plus a default case

Pagination

cursor.enabled: true for list actions
dataKey path verified with --debug
nextKey path verified with --debug
result.next returns the cursor for the next page
Tested against the first page, next page, last page, and empty results

Steps

map_fields step with version: "2"
typecast step with version: "2"
Correct dataSource references between steps

Build Workflow

The build and debug loop this fits into.

Step Functions

Full reference for map_fields, typecast, and the rest.

Expression Syntax

JSONPath and JEXL for the expressions in your mappings.

Build Workflow Implementing Events

​Mapping to your schema

​Give the agent your target schema

​Checklist

​Related

Build Workflow

Step Functions

Expression Syntax

Mapping to your schema

Give the agent your target schema

Checklist

Related