Data validation

Nango automatically validates your integration inputs & outputs. It also offers ways to further customize data validation in code. The guide will walk you through each approach.

Automatic validation

The validation is available during development and production, and does not require any configuration from you:

CLI: Dry Run validation errors are logged and will halt execution when using --validation command option
Production: Validation errors are logged but do not halt execution

Available schema files

When you use Nango CLI, it automatically generates two schema files in the .nango folder:

schema.ts a TypeScript file that contains all your models.
schema.json a JSON Schema file that is used for automatic data validation.

These files can be versioned and integrated into your own codebase, ensuring consistency and reliability across different environments.

Custom Validation

For more advanced use cases, you can generate your own validation schemas using the available files with the tool of your choice.

To create zod schemas you can use ts-to-zod npm package. This tool converts TypeScript definitions into Zod schemas, which can be used for runtime validation in your own Typescript codebase.

npx ts-to-zod .nango/schema.ts schema.zod.ts

You can use zod models in your scripts too

import { myZodModel } from '../../schema.zod.js';

export default async function fetchData(nango: Nango) {
  const response = await nango.get({ endpoint: '/tickets' });
  const isValid = myZodModel.parse(response.json);
  if (isValid) {
    [...]
  }
}

To create zod schemas you can use ts-to-zod npm package. This tool converts TypeScript definitions into Zod schemas, which can be used for runtime validation in your own Typescript codebase.

npx ts-to-zod .nango/schema.ts schema.zod.ts

You can use zod models in your scripts too

import { myZodModel } from '../../schema.zod.js';

export default async function fetchData(nango: Nango) {
  const response = await nango.get({ endpoint: '/tickets' });
  const isValid = myZodModel.parse(response.json);
  if (isValid) {
    [...]
  }
}

You can use go-jsonschema golang package. This tool converts JSON Schema definitions into Golang struct. Note that some syntax are not supported by this package.

go-jsonschema -p main .nango/schema.json > test.go

You can use typify rust package. This tool converts JSON Schema definitions into Rust types. Note that some syntax are not supported by this package.

cargo typify .nango/schema.json

Using `schema.json` in your codebase

JSON Schema is supported in most of the main software languages, here is a non-exhaustive list of how you can directly use this file to validate the records you receive from Nango.

import { Ajv } from 'ajv';
import addFormats from 'ajv-formats';
import jsonSchema from '.nango/schema.json';

// Initiate AJV
const ajv = new Ajv({ allErrors: true, discriminator: true });
addFormats(ajv);

const modelToValidate = 'MyModelName';
const myData = {"id": "hello-word"};

// Compile the JSON schema
const validate = ajv.compile({
  ...jsonSchema,
  ...jsonSchema['definitions'][modelToValidate]
});

// Validate your data
validate(myData);

import { Ajv } from 'ajv';
import addFormats from 'ajv-formats';
import jsonSchema from '.nango/schema.json';

// Initiate AJV
const ajv = new Ajv({ allErrors: true, discriminator: true });
addFormats(ajv);

const modelToValidate = 'MyModelName';
const myData = {"id": "hello-word"};

// Compile the JSON schema
const validate = ajv.compile({
  ...jsonSchema,
  ...jsonSchema['definitions'][modelToValidate]
});

// Validate your data
validate(myData);

package main

import (
	"fmt"
	"log"
	"github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
  sch, err := jsonschema.Compile(".nango/schema.json")
  if err != nil {
    log.Fatalf("%#v", err)
  }

  myData := map[string]interface{}{
		"id": "hello-word",
	}
  if err = sch.Validate(v); err != nil {
    log.Fatalf("%#v", err)
  }
}

use jsonschema::{Draft, JSONSchema};
use serde_json::json;

let data = fs::read_to_string(".nango/schema.json").expect("Unable to read file");
let schema: serde_json::Value = serde_json::from_str(&data).expect("Unable to parse");

let instance = json!("{'id': 'hello-word'}");
let compiled = JSONSchema::compile(&schema).expect("A valid schema");
let result = compiled.validate(&instance);

import json
from jsonschema import validate

with open('.nango/schema.json') as file:
    schema = json.load(file)
    print(schema)

    validate(instance={"id": "hello-word"}, schema=schema)

Getting Started

Guides

Automatic validation

Available schema files

Custom Validation

Using `schema.json` in your codebase

Getting Started

Guides

​Automatic validation

​Available schema files

​Custom Validation

​Using schema.json in your codebase

Automatic validation

Available schema files

Custom Validation

Using `schema.json` in your codebase