> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Defined Output Schemas

> Map provider responses onto an output schema you define, so every provider in a category returns the same shape.

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](/connector-yaml-reference/step-functions):

| Step function                                                       | Role                                                                                               |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`map_fields`](/connector-yaml-reference/step-functions#map_fields) | Maps provider fields onto your `targetFieldKey` names, including enum translation via `enumMapper` |
| [`typecast`](/connector-yaml-reference/step-functions#typecast)     | Runs after `map_fields` to coerce the mapped values to their declared types                        |

<Note>
  Use `version: "2"` for both `map_fields` and `typecast`.
</Note>

## 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:

```markdown theme={null}
---
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:

<AccordionGroup>
  <Accordion title="Schema definition">
    * [ ] Target schema documented before building
    * [ ] All required fields identified
    * [ ] Field types specified (string, number, enum, datetime\_string)
    * [ ] Enum values defined with mappings
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Steps">
    * [ ] `map_fields` step with `version: "2"`
    * [ ] `typecast` step with `version: "2"`
    * [ ] Correct `dataSource` references between steps
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={3}>
  <Card title="Build Workflow" icon="diagram-project" href="/connector-building/build-workflow">
    The build and debug loop this fits into.
  </Card>

  <Card title="Step Functions" icon="code" href="/connector-yaml-reference/step-functions">
    Full reference for `map_fields`, `typecast`, and the rest.
  </Card>

  <Card title="Expression Syntax" icon="brackets-curly" href="/connector-yaml-reference/expression-syntax">
    JSONPath and JEXL for the expressions in your mappings.
  </Card>
</CardGroup>