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

# Esquemas Personalizados

> Define y gestiona esquemas de datos personalizados para una ingesta de datos flexible — en el pipeline de ingestión de datos de gu1 con esquemas personalizados.

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

<Info>
  Los esquemas son específicos de la organización y pueden marcarse como públicos para compartirlos en toda tu organización.
</Info>

## Crear Esquema

Crea un nuevo esquema personalizado para tu fuente de datos.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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
  )
  ```
</CodeGroup>

### Cuerpo de la Solicitud

| Campo         | Tipo    | Requerido | Descripción                                                                |
| ------------- | ------- | --------- | -------------------------------------------------------------------------- |
| `name`        | string  | Sí        | Nombre del esquema (1-255 caracteres)                                      |
| `version`     | string  | No        | Número de versión (predeterminado: "1.0.0")                                |
| `description` | string  | No        | Descripción del esquema                                                    |
| `type`        | enum    | Sí        | Tipo de esquema: `database`, `api`, `file`, `custom`                       |
| `category`    | enum    | Sí        | Categoría: `financial`, `identity`, `compliance`, `transaction`, `general` |
| `schemaData`  | object  | Sí        | Definición del esquema con campos                                          |
| `isPublic`    | boolean | No        | Compartir en toda la organización (predeterminado: false)                  |

### Objeto de Datos del Esquema

| Campo             | Tipo   | Requerido | Descripción                                         |
| ----------------- | ------ | --------- | --------------------------------------------------- |
| `fields`          | array  | Sí        | Array de definiciones de campos                     |
| `metadata`        | object | No        | Metadatos adicionales (formato, codificación, etc.) |
| `analysisResults` | object | No        | Resultados de autodetección                         |

### Definición de Campo

| Campo         | Tipo    | Requerido | Descripción                                              |
| ------------- | ------- | --------- | -------------------------------------------------------- |
| `name`        | string  | Sí        | Nombre del campo                                         |
| `type`        | enum    | Sí        | `string`, `number`, `boolean`, `date`, `array`, `object` |
| `required`    | boolean | No        | ¿Es el campo requerido? (predeterminado: false)          |
| `description` | string  | No        | Descripción del campo                                    |
| `format`      | string  | No        | Sugerencia de formato (ej., "email", "url")              |
| `constraints` | object  | No        | Restricciones de validación                              |
| `examples`    | array   | No        | Valores de ejemplo                                       |

### Objeto de Restricciones

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

### Respuesta

```json theme={null}
{
  "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.

```bash theme={null}
GET /custom-schemas?type=database&category=financial&isPublic=false
```

### Parámetros de Consulta

| Parámetro  | Tipo    | Descripción                                                                            |
| ---------- | ------- | -------------------------------------------------------------------------------------- |
| `type`     | enum    | Filtrar por tipo: `database`, `api`, `file`, `custom`                                  |
| `category` | enum    | Filtrar por categoría: `financial`, `identity`, `compliance`, `transaction`, `general` |
| `isPublic` | boolean | Filtrar por esquemas públicos/privados                                                 |

### Respuesta

```json theme={null}
{
  "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.

```bash theme={null}
GET /custom-schemas/:id
```

### Respuesta

```json theme={null}
{
  "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).

```bash theme={null}
PATCH /custom-schemas/:id
```

### Cuerpo de la Solicitud

```json theme={null}
{
  "description": "Updated description",
  "schemaData": {
    "fields": [
      {
        "name": "company_name",
        "type": "string",
        "required": true,
        "description": "Updated field description"
      }
    ]
  }
}
```

<Warning>
  Actualizar los campos de un esquema puede afectar los mapeos existentes. Revisa los mapeos dependientes antes de realizar cambios.
</Warning>

### Respuesta

```json theme={null}
{
  "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.

```bash theme={null}
DELETE /custom-schemas/:id
```

<Warning>
  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.
</Warning>

### Respuesta

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

```json theme={null}
{
  "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
}
```

## Respuestas de Error

### Error de Validación

```json theme={null}
{
  "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

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

### Esquema Duplicado

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

## Mejores Prácticas

<AccordionGroup>
  <Accordion icon="tag" title="Versionado">
    * 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
  </Accordion>

  <Accordion icon="file-lines" title="Documentació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
  </Accordion>

  <Accordion icon="shield-check" title="Validación">
    * 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
  </Accordion>

  <Accordion icon="users" title="Compartir">
    * 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
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Mapeos de Campos" icon="arrows-left-right" href="/api-reference/data-ingestion/field-mappings">
    Mapea los campos de tu esquema al modelo de entidades de gu1
  </Card>

  <Card title="Detección Inteligente de Campos" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    Autodetecta tipos de campos a partir de datos de muestra
  </Card>

  <Card title="Importar Entidades" icon="upload" href="/en/api-reference/bulk-imports/import-entities">
    Usa tu esquema para importar entidades en masa
  </Card>

  <Card title="Guía de Mapeo de Datos" icon="book" href="/api-reference/data-ingestion/overview">
    Guía completa de flujos de trabajo de mapeo de datos
  </Card>
</CardGroup>