Custom schemas for data ingestion

Overview

Custom Schemas allow you to define the structure of your data before importing it into gu1. Each schema describes the fields, types, validation rules, and metadata for your data source.

Schemas are organization-specific and can be marked as public to share across your organization.

Create Schema

Create a new custom schema for your data source.

curl -X POST http://api.gu1.ai/custom-schemas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "schemaData": {
      "fields": [
        {
          "name": "company_name",
          "type": "string",
          "required": true,
          "description": "Legal company name"
        },
        {
          "name": "tax_id",
          "type": "string",
          "required": true,
          "description": "Tax identification number"
        }
      ]
    },
    "isPublic": false
  }'

const response = await fetch('http://api.gu1.ai/custom-schemas', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Corporate KYB Data',
    version: '1.0.0',
    description: 'Company information for KYB analysis',
    type: 'database',
    category: 'financial',
    schemaData: {
      fields: [
        {
          name: 'company_name',
          type: 'string',
          required: true,
          description: 'Legal company name'
        },
        {
          name: 'tax_id',
          type: 'string',
          required: true,
          description: 'Tax identification number'
        }
      ]
    },
    isPublic: false
  })
});

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

data = {
    'name': 'Corporate KYB Data',
    'version': '1.0.0',
    'description': 'Company information for KYB analysis',
    'type': 'database',
    'category': 'financial',
    'schemaData': {
        'fields': [
            {
                'name': 'company_name',
                'type': 'string',
                'required': True,
                'description': 'Legal company name'
            },
            {
                'name': 'tax_id',
                'type': 'string',
                'required': True,
                'description': 'Tax identification number'
            }
        ]
    },
    'isPublic': False
}

response = requests.post(
    'http://api.gu1.ai/custom-schemas',
    headers=headers,
    json=data
)

Request Body

Field	Type	Required	Description
`name`	string	Yes	Schema name (1-255 characters)
`version`	string	No	Version number (default: “1.0.0”)
`description`	string	No	Schema description
`type`	enum	Yes	Schema type: `database`, `api`, `file`, `custom`
`category`	enum	Yes	Category: `financial`, `identity`, `compliance`, `transaction`, `general`
`schemaData`	object	Yes	Schema definition with fields
`isPublic`	boolean	No	Share across organization (default: false)

Schema Data Object

Field	Type	Required	Description
`fields`	array	Yes	Array of field definitions
`metadata`	object	No	Additional metadata (format, encoding, etc.)
`analysisResults`	object	No	Auto-detection results

Field Definition

Field	Type	Required	Description
`name`	string	Yes	Field name
`type`	enum	Yes	`string`, `number`, `boolean`, `date`, `array`, `object`
`required`	boolean	No	Is field required (default: false)
`description`	string	No	Field description
`format`	string	No	Format hint (e.g., “email”, “url”)
`constraints`	object	No	Validation constraints
`examples`	array	No	Example values

Constraints Object

{
  "minLength": 5,
  "maxLength": 100,
  "pattern": "^[A-Z0-9]+$",
  "enum": ["active", "inactive", "pending"],
  "min": 0,
  "max": 1000
}

Response

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "organizationId": "org_abc123",
    "createdBy": "user_xyz789",
    "isPublic": false,
    "createdAt": "2025-10-03T12:00:00Z",
    "updatedAt": "2025-10-03T12:00:00Z",
    "schemaData": {
      "fields": [...]
    }
  }
}

List Schemas

Get all schemas for your organization with optional filtering.

GET /custom-schemas?type=database&category=financial&isPublic=false

Query Parameters

Parameter	Type	Description
`type`	enum	Filter by type: `database`, `api`, `file`, `custom`
`category`	enum	Filter by category: `financial`, `identity`, `compliance`, `transaction`, `general`
`isPublic`	boolean	Filter by public/private schemas

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Corporate KYB Data",
      "version": "1.0.0",
      "type": "database",
      "category": "financial",
      "isPublic": false,
      "createdAt": "2025-10-03T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "filters": {
      "type": "database",
      "category": "financial"
    }
  }
}

Get Schema

Retrieve a specific schema by ID.

GET /custom-schemas/:id

Response

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "organizationId": "org_abc123",
    "createdBy": "user_xyz789",
    "isPublic": false,
    "createdAt": "2025-10-03T12:00:00Z",
    "updatedAt": "2025-10-03T12:00:00Z",
    "schemaData": {
      "fields": [
        {
          "name": "company_name",
          "type": "string",
          "required": true,
          "description": "Legal company name"
        },
        {
          "name": "tax_id",
          "type": "string",
          "required": true,
          "description": "Tax identification number"
        }
      ],
      "metadata": {
        "sourceFormat": "database",
        "encoding": "UTF-8"
      }
    }
  }
}

Update Schema

Update an existing schema (partial updates supported).

PATCH /custom-schemas/:id

Request Body

{
  "description": "Updated description",
  "schemaData": {
    "fields": [
      {
        "name": "company_name",
        "type": "string",
        "required": true,
        "description": "Updated field description"
      }
    ]
  }
}

Updating a schema’s fields may affect existing mappings. Review dependent mappings before making changes.

Response

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Updated description",
    "updatedAt": "2025-10-03T13:00:00Z",
    ...
  }
}

Delete Schema

Delete a schema permanently.

DELETE /custom-schemas/:id

Deleting a schema will break existing field mappings that depend on it. Ensure no active mappings reference this schema.

Response

{
  "success": true,
  "message": "Schema deleted successfully",
  "deletedId": "550e8400-e29b-41d4-a716-446655440000"
}

Complete Example

Here’s a complete banking customer schema with all features:

{
  "name": "Banking Customer Schema",
  "version": "2.0.0",
  "description": "Complete customer data structure for retail banking",
  "type": "database",
  "category": "financial",
  "schemaData": {
    "fields": [
      {
        "name": "customer_id",
        "type": "string",
        "required": true,
        "description": "Unique customer identifier",
        "format": "uuid",
        "constraints": {
          "pattern": "^CUST[0-9]{8}$"
        },
        "examples": ["CUST12345678", "CUST87654321"]
      },
      {
        "name": "full_name",
        "type": "string",
        "required": true,
        "description": "Customer full legal name",
        "constraints": {
          "minLength": 2,
          "maxLength": 200
        },
        "examples": ["John Doe", "Jane Smith"]
      },
      {
        "name": "email",
        "type": "string",
        "required": true,
        "description": "Primary email address",
        "format": "email",
        "constraints": {
          "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
        },
        "examples": ["john.doe@example.com"]
      },
      {
        "name": "date_of_birth",
        "type": "date",
        "required": true,
        "description": "Customer date of birth",
        "format": "ISO8601",
        "examples": ["1990-01-15"]
      },
      {
        "name": "account_balance",
        "type": "number",
        "required": false,
        "description": "Current account balance in USD",
        "constraints": {
          "min": 0
        },
        "examples": [1000.50, 50000.00]
      },
      {
        "name": "risk_level",
        "type": "string",
        "required": true,
        "description": "Customer risk classification",
        "constraints": {
          "enum": ["low", "medium", "high", "critical"]
        },
        "examples": ["low", "medium"]
      },
      {
        "name": "kyc_verified",
        "type": "boolean",
        "required": true,
        "description": "Whether KYC verification is complete",
        "examples": [true, false]
      },
      {
        "name": "account_types",
        "type": "array",
        "required": false,
        "description": "Types of accounts customer holds",
        "examples": [["checking", "savings"], ["credit"]]
      },
      {
        "name": "address",
        "type": "object",
        "required": false,
        "description": "Customer address details",
        "examples": [
          {
            "street": "123 Main St",
            "city": "New York",
            "state": "NY",
            "zip": "10001",
            "country": "US"
          }
        ]
      }
    ],
    "metadata": {
      "sourceFormat": "database",
      "encoding": "UTF-8",
      "delimiter": null,
      "hasHeaders": true
    }
  },
  "isPublic": false
}

Error Responses

Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid schema data",
    "details": [
      {
        "field": "schemaData.fields[0].type",
        "message": "Invalid field type. Must be one of: string, number, boolean, date, array, object"
      }
    ]
  }
}

Schema Not Found

{
  "success": false,
  "error": {
    "code": "SCHEMA_NOT_FOUND",
    "message": "Schema with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

Duplicate Schema

{
  "success": false,
  "error": {
    "code": "DUPLICATE_SCHEMA",
    "message": "A schema with this name and version already exists"
  }
}

Best Practices

Versioning

Use semantic versioning (1.0.0, 1.1.0, 2.0.0)
Increment major version for breaking changes
Increment minor version for new fields
Increment patch version for description updates

Documentation

Provide clear descriptions for each field
Include examples for complex field types
Document any business rules or constraints
Explain the source of the data

Validation

Always set required: true for mandatory fields
Use constraints to enforce data quality
Validate email formats with regex patterns
Set reasonable min/max values for numbers

Next Steps

Create Field Mappings

Map your schema fields to gu1’s entity model

Smart Field Detection

Auto-detect field types from sample data

Import Entities

Use your schema to bulk import entities

Data Mapping Guide

Complete guide to data mapping workflows

​Overview

​Create Schema

​Request Body

​Schema Data Object

​Field Definition

​Constraints Object

​Response

​List Schemas

​Query Parameters

​Response

​Get Schema

​Response

​Update Schema

​Request Body

​Response

​Delete Schema

​Response

​Complete Example

​Error Responses

​Validation Error

​Schema Not Found

​Duplicate Schema

​Best Practices

​Next Steps

Create Field Mappings

Smart Field Detection

Import Entities

Data Mapping Guide

Overview

Create Schema

Request Body

Schema Data Object

Field Definition

Constraints Object

Response

List Schemas

Query Parameters

Response

Get Schema

Response

Update Schema

Request Body

Response

Delete Schema

Response

Complete Example

Error Responses

Validation Error

Schema Not Found

Duplicate Schema

Best Practices

Next Steps