Skip to main content

​
Descripción General

Los Esquemas Personalizados te permiten definir la estructura de tus datos antes de importarlos a gu1. Cada esquema describe los campos, tipos, reglas de validación y metadatos para tu fuente de datos.
Los esquemas son específicos de la organización y pueden marcarse como públicos para compartirlos en toda tu organización.

​
Crear Esquema

Crea un nuevo esquema personalizado para tu fuente de datos. 
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
  }'

​
Cuerpo de la Solicitud

CampoTipoRequeridoDescripción
namestringSíNombre del esquema (1-255 caracteres)
versionstringNoNúmero de versión (predeterminado: “1.0.0”)
descriptionstringNoDescripción del esquema
typeenumSíTipo de esquema: database, api, file, custom
categoryenumSíCategoría: financial, identity, compliance, transaction, general
schemaDataobjectSíDefinición del esquema con campos
isPublicbooleanNoCompartir en toda la organización (predeterminado: false)

​
Objeto de Datos del Esquema

CampoTipoRequeridoDescripción
fieldsarraySíArray de definiciones de campos
metadataobjectNoMetadatos adicionales (formato, codificación, etc.)
analysisResultsobjectNoResultados de autodetección

​
Definición de Campo

CampoTipoRequeridoDescripción
namestringSíNombre del campo
typeenumSístring, number, boolean, date, array, object
requiredbooleanNo¿Es el campo requerido? (predeterminado: false)
descriptionstringNoDescripción del campo
formatstringNoSugerencia de formato (ej., “email”, “url”)
constraintsobjectNoRestricciones de validación
examplesarrayNoValores de ejemplo

​
Objeto de Restricciones

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

​
Respuesta

{
  "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": [...]
    }
  }
}

​
Listar Esquemas

Obtiene todos los esquemas de tu organización con filtrado opcional. 
GET /custom-schemas?type=database&category=financial&isPublic=false

​
Parámetros de Consulta

ParámetroTipoDescripción
typeenumFiltrar por tipo: database, api, file, custom
categoryenumFiltrar por categoría: financial, identity, compliance, transaction, general
isPublicbooleanFiltrar por esquemas públicos/privados

​
Respuesta

{
  "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"
    }
  }
}

​
Obtener Esquema

Recupera un esquema específico por ID. 
GET /custom-schemas/:id

​
Respuesta

{
  "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"
      }
    }
  }
}

​
Actualizar Esquema

Actualiza un esquema existente (se admiten actualizaciones parciales). 
PATCH /custom-schemas/:id

​
Cuerpo de la Solicitud

{
  "description": "Updated description",
  "schemaData": {
    "fields": [
      {
        "name": "company_name",
        "type": "string",
        "required": true,
        "description": "Updated field description"
      }
    ]
  }
}
Actualizar los campos de un esquema puede afectar los mapeos existentes. Revisa los mapeos dependientes antes de realizar cambios.

​
Respuesta

{
  "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",
    ...
  }
}

​
Eliminar Esquema

Elimina un esquema permanentemente. 
DELETE /custom-schemas/:id
Eliminar un esquema romperá los mapeos de campos existentes que dependan de él. Asegúrate de que no haya mapeos activos que referencien este esquema.

​
Respuesta

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

​
Ejemplo Completo

Aquí hay un esquema completo de cliente bancario con todas las características: 
{
  "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": ["[email protected]"]
      },
      {
        "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
}

​
Respuestas de Error

​
Error de Validación

{
  "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"
      }
    ]
  }
}

​
Esquema No Encontrado

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

​
Esquema Duplicado

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

​
Mejores Prácticas

  • Usa versionado semántico (1.0.0, 1.1.0, 2.0.0)
  • Incrementa la versión mayor para cambios que rompen compatibilidad
  • Incrementa la versión menor para nuevos campos
  • Incrementa la versión de parche para actualizaciones de descripción
  • Proporciona descripciones claras para cada campo
  • Incluye ejemplos para tipos de campos complejos
  • Documenta cualquier regla de negocio o restricción
  • Explica el origen de los datos
  • Siempre establece required: true para campos obligatorios
  • Usa restricciones para garantizar la calidad de los datos
  • Valida formatos de email con patrones regex
  • Establece valores mínimos/máximos razonables para números
  • Marca los esquemas comunes como públicos para uso en toda la organización
  • Mantén los esquemas sensibles como privados
  • Documenta cualquier dependencia entre esquemas
  • Coordina las actualizaciones de esquemas con tu equipo

​
Próximos Pasos

Crear Mapeos de Campos

Mapea los campos de tu esquema al modelo de entidades de gu1

Detección Inteligente de Campos

Autodetecta tipos de campos a partir de datos de muestra

Importar Entidades

Usa tu esquema para importar entidades en masa

Guía de Mapeo de Datos

Guía completa de flujos de trabajo de mapeo de datos