Schemas

For an overview of schema concepts and available data types, see Schemas.

Prerequisites

Kadoa account with API key
SDK installed: npm install @kadoa/node-sdk or uv add kadoa-sdk

Working with Schemas

Define the structure of data you want to extract using the builder API:

const extraction = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce"],
    name: "Product Extraction",
    extraction: (builder) =>
      builder
        .entity("Product")
        .field("title", "Product name", "STRING", { example: "Laptop" })
        .field("price", "Product price", "MONEY")
        .field("inStock", "Availability", "BOOLEAN")
        .field("rating", "Star rating 1-5", "NUMBER"),
  })
  .create();

from kadoa_sdk import ExtractOptions, FieldOptions, KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

extract_options = ExtractOptions(
    urls=["https://sandbox.kadoa.com/ecommerce"],
    name="Product Extraction",
    extraction=lambda builder: builder.entity("Product")
    .field("title", "Product name", "STRING", FieldOptions(example="Laptop"))
    .field("price", "Product price", "MONEY")
    .field("inStock", "Availability", "BOOLEAN")
    .field("rating", "Star rating 1-5", "NUMBER"),
)

extraction = client.extract(extract_options).create()
print(f"Extraction created successfully: {extraction}")

Reusable Schemas

For consistent data extraction across multiple workflows, you can create and manage schemas separately using the Schema Management API. Schemas can also be bundled into templates along with a prompt and notification settings.

Schema Management API

The Schema Management API allows you to create, retrieve, and delete schemas programmatically. Saved schemas can be reused across multiple extractions, ensuring consistent data structure.

When to Use Saved Schemas

Use saved schemas when you:

Extract the same data structure from multiple websites
Want to maintain consistent field definitions across workflows
Need to programmatically manage schema lifecycle
Share schemas across different parts of your application

For one-off extractions, inline schema definitions (shown above) are simpler and don’t require separate schema management.

If you need to apply the same schema, prompt, and notifications to multiple workflows, consider using templates instead. Templates bundle all three into a versioned configuration.

Create a Schema

const schema = await client.schema.createSchema({
  name: schemaName,
  entity: "Product",
  fields: [
    {
      name: "title",
      description: "Product name",
      fieldType: "SCHEMA",
      dataType: "STRING",
      example: "iPhone 15 Pro",
    },
    {
      name: "price",
      description: "Product price",
      fieldType: "SCHEMA",
      dataType: "MONEY",
    },
    {
      name: "inStock",
      description: "Availability",
      fieldType: "SCHEMA",
      dataType: "BOOLEAN",
    },
    {
      name: "rating",
      description: "Star rating",
      fieldType: "SCHEMA",
      dataType: "NUMBER",
    },
  ],
});

console.log("Schema created:", schema.id);

from kadoa_sdk import KadoaClient, KadoaClientConfig
from kadoa_sdk.schemas import (
    CreateSchemaRequest,
    DataField,
    FieldExample,
    SchemaField,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

# Create field objects
fields = [
    SchemaField(
        actual_instance=DataField(
            name="title",
            description="Product name",
            fieldType="SCHEMA",
            dataType="STRING",
            example=FieldExample(actual_instance="iPhone 15 Pro"),
        )
    ),
    SchemaField(
        actual_instance=DataField(
            name="price",
            description="Product price",
            fieldType="SCHEMA",
            dataType="MONEY",
        )
    ),
    SchemaField(
        actual_instance=DataField(
            name="inStock",
            description="Availability",
            fieldType="SCHEMA",
            dataType="BOOLEAN",
        )
    ),
    SchemaField(
        actual_instance=DataField(
            name="rating",
            description="Star rating",
            fieldType="SCHEMA",
            dataType="NUMBER",
        )
    ),
]

# Create schema request
create_request = CreateSchemaRequest(
    name="Product Schema",
    entity="Product",
    fields=fields,
)

schema = client.schema.create_schema(create_request)

print("Schema created:", schema.id)

Get a Schema

Retrieve an existing schema by ID:

const schema = await client.schema.getSchema(schemaId);

console.log(schema.name); // 'Product Schema'
console.log(schema.entity); // 'Product'
console.log(schema.schema); // Array of field definitions

from kadoa_sdk import KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))
schema_id = "YOUR_SCHEMA_ID"

schema = client.schema.get_schema(schema_id)

print(schema.name)
print(schema.entity)
print(schema.var_schema)  # Array of field definitions

Delete a Schema

Remove a schema when it’s no longer needed:

await client.schema.deleteSchema(schemaId);

from kadoa_sdk import KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))
schema_id = "YOUR_SCHEMA_ID"

client.schema.delete_schema(schema_id)

Deleting a schema does not affect existing workflows or extractions that were created using it.

Update a Schema

Modify an existing schema’s name, entity, or fields:

const updated = await client.schema.updateSchema(schemaId, {
  name: updatedName,
  entity: "Product",
  fields: [
    {
      name: "title",
      description: "Product name",
      fieldType: "SCHEMA",
      dataType: "STRING",
      example: "MacBook Pro",
    },
    {
      name: "price",
      description: "Product price in USD",
      fieldType: "SCHEMA",
      dataType: "MONEY",
    },
    {
      name: "sku",
      description: "Stock keeping unit",
      fieldType: "SCHEMA",
      dataType: "STRING",
      example: "Stock keeping unit",
    },
  ],
});

console.log("Schema updated:", updated.id);

from kadoa_sdk import KadoaClient, KadoaClientConfig
from kadoa_sdk.schemas import (
    DataField,
    FieldExample,
    SchemaField,
    UpdateSchemaRequest,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))
schema_id = "YOUR_SCHEMA_ID"

update_request = UpdateSchemaRequest(
    name="Updated Product Schema",
    entity="Product",
    fields=[
        SchemaField(
            actual_instance=DataField(
                name="title",
                description="Product name",
                fieldType="SCHEMA",
                dataType="STRING",
                example=FieldExample(actual_instance="MacBook Pro"),
            )
        ),
        SchemaField(
            actual_instance=DataField(
                name="price",
                description="Product price in USD",
                fieldType="SCHEMA",
                dataType="MONEY",
            )
        ),
        SchemaField(
            actual_instance=DataField(
                name="sku",
                description="Stock keeping unit",
                fieldType="SCHEMA",
                dataType="STRING",
                example=FieldExample(actual_instance="SKU-123"),
            )
        ),
    ],
)

updated = client.schema.update_schema(schema_id, update_request)
print("Schema updated:", updated.id)

Use a Saved Schema

Reference a saved schema in your extraction:

const extraction = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce"],
    name: "Product Extraction",
    extraction: () => ({ schemaId }),
  })
  .create();

const result = await extraction.run();

from kadoa_sdk import ExtractOptions, KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))
schema_id = "YOUR_SCHEMA_ID"

extract_options = ExtractOptions(
    urls=["https://sandbox.kadoa.com/ecommerce"],
    name="Product Extraction - PY-SCHEMAS-005",
    extraction=lambda _: {"schemaId": schema_id},
)

extraction = client.extract(extract_options).create()

run_result = extraction.run()
print("Extraction completed:", run_result)

Field Types

Schemas support four types of fields:

Regular fields - Structured data extraction (shown above)
Classification fields - Categorize content into predefined labels
Source fields - Capture values Kadoa already holds, such as the page URL or the full page HTML
Function fields - Fields Kadoa computes for you, such as a stable unique ID

Available Data Types

For regular fields, specify the dataType: STRING • NUMBER • BOOLEAN • DATE • DATETIME • MONEY • IMAGE • LINK • OBJECT • ARRAY See data type details and examples →

Classification Fields

Categorize extracted content into predefined labels:

const schema = await client.schema.createSchema({
  name: schemaName,
  entity: "Article",
  fields: [
    {
      name: "title",
      description: "Article headline",
      fieldType: "SCHEMA",
      dataType: "STRING",
      example: "Breaking News",
    },
    {
      name: "category",
      description: "Article category",
      fieldType: "CLASSIFICATION",
      categories: [
        { title: "Technology", definition: "Tech news and updates" },
        { title: "Business", definition: "Business and finance" },
        { title: "Sports", definition: "Sports coverage" },
      ],
    },
  ],
});

from kadoa_sdk import KadoaClient, KadoaClientConfig
from kadoa_sdk.schemas import (
    Category,
    ClassificationField,
    CreateSchemaRequest,
    DataField,
    FieldExample,
    SchemaField,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

# Create categories
categories = [
    Category(title="Technology", definition="Tech news and updates"),
    Category(title="Business", definition="Business and finance"),
    Category(title="Sports", definition="Sports coverage"),
]

# Create fields
fields = [
    SchemaField(
        actual_instance=DataField(
            name="title",
            description="Article headline",
            fieldType="SCHEMA",
            dataType="STRING",
            example=FieldExample(actual_instance="Breaking News"),
        )
    ),
    SchemaField(
        actual_instance=ClassificationField(
            name="category",
            description="Article category",
            fieldType="CLASSIFICATION",
            categories=categories,
        )
    ),
]

# Create schema request
create_request = CreateSchemaRequest(
    name="Article Schema",
    entity="Article",
    fields=fields,
)

schema = client.schema.create_schema(create_request)
print("Schema with classification created:", schema.id)

Function Fields

Functions add fields whose values Kadoa computes for you instead of extracting them from the page. A function field is a regular SCHEMA field with an output dataType, a top-level mapper, and optional mapperConfig. Configuration is flat: for example, mapper: "categoryClassifier" uses mapperConfig: { categoryName: "generic_english" }. Classification retains its own field shape (fieldType: CLASSIFICATION), covered above. The previous params.mapper representation remains accepted for compatibility. For example, add a stable unique ID to each record:

const schema = await client.schema.createSchema({
  name: schemaName,
  entity: "Product",
  fields: [
    {
      name: "title",
      description: "Product name",
      fieldType: "SCHEMA",
      dataType: "STRING",
      example: "Laptop",
    },
    {
      name: "recordId",
      description: "Unique ID",
      fieldType: "SCHEMA",
      dataType: "STRING",
      mapper: "stableUniqueId",
    },
  ],
});

console.log("Schema created:", schema.id);

Functions vary by workspace; the API rejects fields yours isn’t enabled for.

Source Fields

To keep raw page content, add a regular SCHEMA field with a params.sourceKey instead of an extraction. Supported source keys: link (page URL), allExtracts.fullHtml, and allExtracts.fullMarkdown.

const schema = await client.schema.createSchema({
  name: schemaName,
  entity: "Article",
  fields: [
    {
      name: "pageUrl",
      description: "Page URL",
      fieldType: "SCHEMA",
      dataType: "LINK",
      params: { sourceKey: "link" },
    },
    {
      name: "fullHtml",
      description: "Full page HTML",
      fieldType: "SCHEMA",
      dataType: "STRING",
      params: { sourceKey: "allExtracts.fullHtml" },
    },
  ],
});

console.log("Schema created:", schema.id);

Foundations

Security & Compliance

Build with UI

Build with Code

Integrations

Prerequisites

Working with Schemas

Reusable Schemas

Schema Management API

When to Use Saved Schemas

Create a Schema

Get a Schema

Delete a Schema

Update a Schema

Use a Saved Schema

Field Types

Available Data Types

Classification Fields

Function Fields

Source Fields

​Prerequisites

​Working with Schemas

​Reusable Schemas

​Schema Management API

​When to Use Saved Schemas

​Create a Schema

​Get a Schema

​Delete a Schema

​Update a Schema

​Use a Saved Schema

​Field Types

​Available Data Types

​Classification Fields

​Function Fields

​Source Fields

Prerequisites

Working with Schemas

Reusable Schemas

Schema Management API

When to Use Saved Schemas

Create a Schema

Get a Schema

Delete a Schema

Update a Schema

Use a Saved Schema

Field Types

Available Data Types

Classification Fields

Function Fields

Source Fields