Data validation

How to validate data in your functions and in your app

Nango offers data validation at two levels: inside your Nango functions (when calling external APIs) and in your application code (when consuming function responses).

Validate API responses in Nango functions

Use Zod to validate data you receive from and send to external APIs. The CLI will also surface type errors during dry runs when using the --validation option.

import * as z from 'zod';

const dataFromAPI = z.object({
  ticketId: z.string(),
});

export default createSync({
  exec: async (nango) => {
    const response = await nango.get({ endpoint: '/tickets' });
    const isValid = dataFromAPI.parse(response.json);
    if (isValid) {
      [...]
    }
  },
});

Validate Nango function responses in your app

TypeScript types (compile-time)

Use z.infer to derive TypeScript types from your Zod schemas and export them from your function files:

// In: github/syncs/fetchIssues.ts (Nango function)
export type GithubIssue = z.infer<typeof issueSchema>;

Then import the types in your application code:

import type { GithubIssue } from './nango-integrations/github/syncs/fetchIssues';

const issues = await nango.listRecords<GithubIssue>({ ... });

JSON Schema (runtime, language-agnostic)

When you run nango compile or nango deploy, Nango generates a nango.json file in the .nango folder. Each sync entry includes a json_schema property with the JSON Schema for its models:

// .nango/nango.json (simplified)
[
  {
    "providerConfigKey": "github",
    "syncs": [
      {
        "name": "fetchIssues",
        "output": ["GithubIssue"],
        "json_schema": {
          "definitions": {
            "GithubIssue": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "title": { "type": "string" },
                "state": { "type": "string" }
              },
              "required": ["id", "title", "state"],
              "additionalProperties": false
            }
          }
        }
      }
    ]
  }
]

You can extract a sync’s json_schema object and use it with any JSON Schema validator in your language of choice (e.g., ajv in TypeScript, jsonschema in Python, jsonschema in Rust, santhosh-tekuri/jsonschema in Go).

For tools, convert the input and output Zod schemas directly. Zod v4 supports JSON Schema conversion natively with z.toJSONSchema():

import { z } from 'zod';
import { issueSchema } from './nango-integrations/github/syncs/fetchIssues';

const jsonSchema = z.toJSONSchema(issueSchema);

Related guides

• Tools - validate tool inputs and outputs.
• Sync functions - validate synced record models.
• Unified APIs - normalize provider data behind stable schemas.
• Testing - cover validation behavior in tests.