Schemas

Single-description editing rolls out workflow by workflow. A workflow keeps separate Description, Extraction instructions and Example inputs until it is selected for the new editor. Templates retain these separate inputs. Keep those values separate while these inputs are shown.

A schema defines the data a workflow extracts. It lists each field’s name, data type, and description. You can reuse one schema across many workflows. For example, to extract store locations from 5 different websites, create one schema and use it for all of them. API V6 uses description for field meaning, instructions, and sample values. Older API versions retain separate instruction and example inputs and their existing response contract until an individual workflow is explicitly migrated. V6 responses combine the labeled contents into description. Shared schemas and templates are not switched with a workflow. Schemas and templates created through either version remain readable through the other version.

How the agent builds a schema

When you create a workflow with Kadoa’s agent, it builds the schema for you.

If you name the fields in your prompt, for example “extract title, price, and rating”, the agent uses exactly those.
If you don’t, the agent recommends fields based on the source.

Either way, you can adjust every field before you approve the workflow. In the dashboard, the schema lives in the workflow’s Schema tab. The Pipeline tab shows how fields are transformed after extraction. Schema tab with seven fields and the Reorder and JSON controls. A key icon marks the jobId key field, salaryMin is marked Code, and the expanded titleEnglish field is marked AI and shows what it is made from, its description, and how it is computed.

Schema tab with seven fields and the Reorder and JSON controls. A key icon marks the jobId key field, salaryMin is marked Code, and the expanded titleEnglish field is marked AI and shows what it is made from, its description, and how it is computed.

If your workflow uses a template, the template manages its schema. Edit the schema in the template instead.

Field kinds

Every field gets its value in one of three ways.

Kind	Where the value comes from	Examples	How to add it
Extracted field	The agent reads it from the page	Title, price, posted date	Add field, then enter a name, description, and type
Function field	Kadoa computes it for each record	Custom categories, Unique ID	Add field, then select a built-in function
Source field	Kadoa copies it from the page it loaded	Page URL, full HTML, full Markdown	With the SDK or API

In the Schema tab, a field Kadoa computes, with a function or a transformation, shows Code or AI to say how its value is made. Select the field to see the fields its value is made from. In the SDK and API, each kind has its own shape:

Kind	API shape
Extracted field	`fieldType: "SCHEMA"` with a `dataType`
Function field	Custom categories: `fieldType: "CLASSIFICATION"` with `categories`. Other functions: `fieldType: "SCHEMA"` with a `mapper`
Source field	`fieldType: "SCHEMA"` with `params.sourceKey`

Function fields

A function field holds a value Kadoa computes instead of reading it from the page. Each function has an output data type. Functions marked AI use a model on every record.

Custom categories puts each record into one of the categories you define, for example sentiment or priority.
Unique ID gives each record a stable identifier. It works well as a key field.

Custom categories is available to every team. Other functions depend on your team. The editor lists only the functions your team can use.

See Functions for what each function does. To add one, see Add a function field.

Source fields

A source field keeps raw page content next to the extracted data. It holds the page URL, the full HTML, or the full Markdown of each page. The schema editor does not add source fields. Add them with the SDK or API, as shown in Add a source field. Every schema has key fields that identify a record across runs.

Transformations

For batch workflows, GET /v4/workflows/{id} returns pendingFields, an array of customer field names added or changed relative to the published run. Key toggles and equivalent legacy schema formats do not count as changes. Before the first published run, all customer fields are pending. An empty array means no fields differ; the property is omitted for realtime workflows or when an existing published run has no schema snapshot. Changes apply to future runs and do not backfill historical rows. Some workflows transform data after extraction, for example to categorize records or compute derived fields. A transformation reads input fields as context and produces output fields. Each output field has a summary of how it is computed, when one is available. To review a workflow’s transformation:

In the dashboard, open the Pipeline panel.
With the API, read the transformation object from Get workflow by ID.

See Transformations for how they work and how to add one.

Create or edit fields

Dashboard
SDK & API
MCP

To edit a field:

Open the workflow and select the Schema tab.
Select the field to see its details.
Select the pencil icon to open the inline edit form.
Change the field and select Done.
Select Save changes.

To add a field:

In the Schema tab, select Add field.
Enter a Name, a Description that says what the value is, where to find it, and its format, and a Type. Then select Add field.
Select Save changes.

New and changed fields show Not built yet until a run produces them. The change applies from that run on; earlier rows stay as they are.To edit all fields at once, select JSON. To change the field order, select Reorder.

You need a Kadoa API key and the SDK. Install it with npm install @kadoa/node-sdk or uv add kadoa-sdk.Define the fields inline with the builder API when you create a workflow:

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

Inline fields suit one-off extractions and need no separate schema management. To share fields across workflows, see Reuse a schema.

Ask your AI tool, for example:

> Add a rating field to my Product Extraction workflow

Your AI tool reads the current schema with get_workflow and saves it with update_workflow. update_workflow replaces the whole schema, so the update must list every field you want to keep.

Add a function field

Dashboard
SDK & API

In the Schema tab, select Add field.
Under Or use a built-in function, select a function, such as Custom categories or Unique ID. Functions marked AI use a model on every record.
Configure the function and select Add field.
Select Save changes.

A function field is a regular SCHEMA field with an output dataType, a top-level mapper, and optional mapperConfig. The configuration is flat. For example, mapper: "categoryClassifier" uses mapperConfig: { categoryName: "generic_english" }. The API still accepts the previous params.mapper representation for compatibility.Custom categories is called a classification field in the API. It keeps its own field shape, fieldType: "CLASSIFICATION" with categories, and puts each record into one of the categories you define:

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)

Other functions use mapper. 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 team. The API rejects function fields your team can’t use. See Functions for what each one does.

Add a source field

You add source fields with the SDK or API. The dashboard schema editor does not add them. Add a SCHEMA field with params.sourceKey instead of an extraction instruction. These source keys are supported:

Source key	Value
`link`	Page URL
`allExtracts.fullHtml`	Full page HTML
`allExtracts.fullMarkdown`	Full page Markdown

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);

Reuse a schema

Dashboard
SDK & API
MCP

To reuse a schema across workflows, save it in a template. A template packages a prompt, schema, data quality rules, and notification settings into one versioned unit.

Open Templates and select Create template.
Define your fields in the Schema tab.
When you create a workflow, select the template to pre-fill its schema.

To start from an existing workflow’s schema, open the workflow menu and select Save as template.After you publish a new template version, apply it to the linked workflows. See Update a template.

Save a schema with the Schema Management API, then reference it from many workflows. Use a saved schema when you:

Extract the same data structure from multiple websites
Want consistent field definitions across workflows
Manage the schema lifecycle from code
Share schemas across different parts of your application

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)

Reference the saved schema in an 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)

To get, update, or delete a saved schema, see Manage saved schemas.

To apply the same schema, prompt, and notifications to many workflows, use templates instead. A template bundles all three into a versioned configuration.

Ask your AI tool, for example:

> Create a template from my Product Extraction workflow

Your AI tool uses save_workflow_as_template. To create a workflow from that template, it passes templateId to create_workflow.

Manage saved schemas

You manage saved schemas with the SDK or API.

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

Update a schema

Change a 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)

Delete a schema

Remove a schema you no longer need:

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 created with it.

Data types

Each extracted field has a data type. Kadoa uses it to extract and validate the value.

Data type	Dashboard label	Description	Example use cases
STRING	Text	String or text content	Product names, descriptions, article headlines
NUMBER	Number	Numeric values, integers or decimals	Quantities, ratings, scores, counts
BOOLEAN	Boolean	True or false values	Availability status, feature flags, yes/no indicators
DATE	Date	Date values	Publication dates, deadlines, event dates
DATETIME	DateTime	Date and time values	Timestamps, scheduled times, last updated
MONEY	Money	Currency and monetary values	Prices, costs, revenue, discounts
IMAGE	Image	Image URLs and references	Product photos, thumbnails, profile pictures
LINK	Link	URLs and hyperlinks	Product pages, external links, social media
OBJECT	JSON Object	Nested or complex JSON structures	Structured metadata, complex configurations
ARRAY	Array	Lists of values	Tags, categories, multiple images, feature lists

Data type formats

Some data types return structured values:

Data type	Format	Example
MONEY	`{"amount": number, "currencyCode": string}`	`$124.50` → `{"amount": 12450, "currencyCode": "USD"}`

The amount field is always in the smallest currency unit, for example cents for USD and pence for GBP.

For help with a custom schema, contact support.

Get started

Concepts

Security & Compliance

Build workflows

Templates

Monitor & alert

MCP

Integrations

Administration

How the agent builds a schema

Field kinds

Function fields

Source fields

Transformations

Create or edit fields

Add a function field

Add a source field

Reuse a schema

Manage saved schemas

Get a schema

Update a schema

Delete a schema

Data types

Data type formats

​How the agent builds a schema

​Field kinds

​Function fields

​Source fields

​Transformations

​Create or edit fields

​Add a function field

​Add a source field

​Reuse a schema

​Manage saved schemas

​Get a schema

​Update a schema

​Delete a schema

​Data types

​Data type formats

​Related

How the agent builds a schema

Field kinds

Function fields

Source fields

Transformations

Create or edit fields

Add a function field

Add a source field

Reuse a schema

Manage saved schemas

Get a schema

Update a schema

Delete a schema

Data types

Data type formats

Related