Documentation Index
Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
Use this file to discover all available pages before exploring further.
Options are a powerful feature in Kodexa that allow you to define configuration parameters for components, capture user input, and enable flexible customization of behavior. They provide a declarative way to create configuration interfaces without writing UI code.
Quick Start
Options appear throughout Kodexa in metadata definitions for assistants, models, taxonomies (data definitions), actions, and pipeline steps. Here’s a simple example:
options:
- name: hostname
type: string
label: Server Hostname
description: The hostname or IP address of the server
required: true
- name: port
type: number
label: Port Number
description: The port number for the connection
default: 22
How Users Experience Options
Options create interactive configuration interfaces in several areas:
Assistant Configuration
When users add an assistant to their project, they can configure it through options you define:
Document Labeling Properties
When labeling documents, users can set properties on labels based on options defined in your taxonomy:
Options keep users focused on content while configuring the system to their needs.
Complete Option Types Reference
Kodexa supports 24+ option types organized into categories:
string / text
A text input field with optional multiline support.
options:
- name: description
type: string
label: Description
description: Enter a description
placeholder: Type here...
lines (number): Number of lines for multiline input (default: 1)password (boolean): Mask input as password field (default: false)placeholder (string): Placeholder text when empty
Special Features:
- Password fields integrate with organization secrets
- Automatically switches between text input and textarea based on
lines
- Secret references stored as
${secret.secretName}
Example with multiline:
- name: notes
type: string
label: Notes
description: Additional notes
lines: 5
placeholder: Enter detailed notes here
number
Numeric input with optional constraints.
options:
- name: timeout
type: number
label: Timeout (seconds)
description: Request timeout in seconds
default: 30
min: 1
max: 300
min (number): Minimum allowed valuemax (number): Maximum allowed valuestep (number): Increment/decrement step (default: 1)
boolean
Checkbox or toggle switch for true/false values.
options:
- name: enabled
type: boolean
label: Enable Feature
description: Enable this feature
default: false
- View mode displays color-coded badges (green for true, gray for false)
- Can specify custom labels for true/false states
select
Dropdown selection from predefined values.
options:
- name: format
type: select
label: Output Format
description: Choose the output format
possibleValues:
- label: JSON
value: json
- label: CSV
value: csv
- label: XML
value: xml
possibleValues: Array of {label, value} objectsmultiple (boolean): Allow multiple selections (default: false)
Code & Script Types
code
Full code editor with syntax highlighting.
options:
- name: transform_script
type: code
label: Transform Script
description: Python script to transform data
language: python
height: 400px
default: |
def transform(data):
return data
language (string): Programming language for syntax highlighting (default: “python”)height (string): Editor height (default: “300px”)
Special Features:
- Full code editor experience
- View mode renders as formatted
<pre> block
- Scrollable with max-height in view mode
script / pythonScript / javascript
Script input for code snippets.
options:
- name: validation_script
type: script
label: Validation Script
description: Script to validate data
required: true
default: |
return {
"valid": true
}
documentStore
Select a document store from the project.
options:
- name: source_store
type: documentStore
label: Source Document Store
description: Select the document store to process
required: true
moduleStore
Select a module store from the project.
options:
- name: module
type: moduleStore
label: Module Store
description: Select the module to use
required: true
tableStore
Select a data store from the project.
options:
- name: output_store
type: tableStore
label: Output Data Store
description: Select where to store extracted data
required: true
taxonomyStore
Select a taxonomy (data definition) from the project.
options:
- name: taxonomy
type: taxonomyStore
label: Data Definition
description: Select the taxonomy to use
required: true
workspace
Select a workspace from available workspaces.
options:
- name: workspace
type: workspace
label: Workspace
description: Select the target workspace
required: true
showDescription (boolean): Show workspace description (default: true)
Document & Content Types
document
Search and select a specific document.
options:
- name: template_document
type: document
label: Template Document
description: Select a document to use as template
required: true
- Live search with autocomplete
- Shows document path in results
- Returns
storeRef/documentId format
- Configurable page size for results
Select a data form configuration from the project.
options:
- name: form
type: data-form
label: Data Form
description: Select the data form configuration
required: true
Taxonomy & Label Types
taxon
Select a taxonomy element (data element).
options:
- name: root_element
type: taxon
label: Root Data Element
description: Select the root data element
required: true
onlyGroups (boolean): Show only group taxons (default: false)allowEmpty (boolean): Allow empty selection (default: true)filterable (boolean): Enable filtering (default: true)
Special Features:
- Hierarchical taxonomy navigation
- Case-insensitive search across label and parent label
- Custom dropdown item rendering
taxon_label
Select a taxonomy label.
options:
- name: label_type
type: taxon_label
label: Label Type
description: Select the label type to use
required: true
taxon-lookup
Hierarchical taxonomy search with full path display.
options:
- name: target_taxon
type: taxon-lookup
label: Target Data Element
description: Search and select a data element
taxonomyTypes:
- CONTENT
- MODEL
showFullPath: true
taxonomyTypes (array): Types of taxonomies to include (default: [“CONTENT”, “MODEL”])showFullPath (boolean): Show full taxonomy path (default: true)
Special Features:
- Flattens taxonomy tree for search
- Displays full path with parent labels
- Chip-based display with custom styling
- Excludes METADATA value paths
taxon_with_properties
Select a taxonomy element and configure its properties.
options:
- name: field_config
type: taxon_with_properties
label: Field Configuration
description: Select field and configure properties
taxonomyTypes:
- CONTENT
- MODEL
additionalOptions:
- name: required
type: boolean
label: Required Field
- name: validation
type: select
label: Validation Rule
possibleValues:
- label: None
value: none
- label: Numeric
value: numeric
taxonomyTypes (array): Types of taxonomies to includeadditionalOptions (array): Nested options for the selected taxon
Special Features:
- Two-tier configuration (selection + properties)
- Tabbed interface for additional options
- Recursive option rendering
- Stores both tag path and options object
Status Types
documentStatus
Select a document status from the project.
options:
- name: target_status
type: documentStatus
label: Target Status
description: Status to apply to documents
required: true
attributeStatus
Select an attribute status from the project.
options:
- name: attribute_status
type: attributeStatus
label: Attribute Status
description: The attribute status to use
required: true
clearable (boolean): Allow clearing the selection (default: true)
taskStatus
Select a task status from the project.
options:
- name: task_status
type: taskStatus
label: Task Status
description: Select the task status
required: true
- Color-coded badges with dynamic background colors
- Contrasting text color based on background
- Custom item rendering in dropdown
task-templates
Select a task template from the project.
options:
- name: template
type: task-templates
label: Task Template
description: Select a task template to apply
required: true
- Async data loading from project store
- Reactive updates when templates change
Cloud AI Model Types
cloud-model
Select a cloud-based AI model.
options:
- name: llm_model
type: cloud-model
label: Language Model
description: Select the AI model to use
showDescription: true
showProvider: true
showDescription (boolean): Show model description as hint (default: true)showProvider (boolean): Show provider in model name (default: true)
Special Features:
- Local storage caching (3-minute expiry) to reduce API calls
- Filters non-embedding active models
- Combines model name + provider for display
- Alphabetically sorted
- Paginated results (pageSize: 50)
cloud-embedding
Select a cloud embedding model.
options:
- name: embedding_model
type: cloud-embedding
label: Embedding Model
description: Select the embedding model
showDescription: true
showDescription (boolean): Show model description (default: true)
Special Features:
- Filters for embedding models specifically
- API integration with pagination
- Dynamic loading state
Pipeline Types
pipeline
Configure an entire pipeline with steps.
options:
- name: processing_pipeline
type: pipeline
label: Processing Pipeline
description: Configure the document processing pipeline
required: true
- Visual pipeline editor
- Drag-and-drop step ordering
- Step configuration interface
pipelineModelOptions
Configure options for models within a pipeline.
options:
- name: model_configs
type: pipelineModelOptions
label: Model Configurations
description: Configure options for pipeline models
showTabs: true
showTabs (boolean): Organize options in tabs (default: true)
Display Types
alert
Display an informational alert message.
options:
- name: info_message
type: alert
label: Information
markdown: |
**Important:** This feature requires additional configuration.
Please ensure you have set up the API credentials before proceeding.
type: info
markdown (text): Markdown content to displaytype (select): Alert style - info, warning, error, success
Special Features:
- Renders markdown content
- Dynamic styling based on alert type
- Material Design icons
article
Display or reference a knowledge base article.
options:
- name: help_article
type: article
label: Help Documentation
articleId: "12345"
slide: 1
articleId (string): ID of the article to displaytext (text): Direct text content (alternative to articleId)slide (number): Specific slide number to display
Special Features:
- Integrates with knowledge base
- Slide-based navigation support
- Can display by ID or direct text
Specialized Types
chart
Select chart visualization type.
options:
- name: visualization
type: chart
label: Chart Type
description: Select how to visualize the data
default: bar
type (select): Chart type - bar or pie
label
Select or enter a document label.
options:
- name: classification
type: label
label: Document Label
description: The label to apply
multiple: false
multiple (boolean): Allow multiple label selection (default: false)
Special Features:
- Fetches available labels from project
- Custom item rendering
- Supports future multi-select capability
simpleExpression
Enter a simple expression that can be evaluated.
options:
- name: calculation
type: simpleExpression
label: Expression
description: Enter a mathematical expression
default: "3+5"
- Single-line text input
- Can be evaluated to compute a value
Working with Lists and Objects
Two of the most powerful option types are list and object, which allow you to define complex, structured data. Understanding how to use these properly is critical for building flexible configurations.
List Options
Lists allow you to define arrays of values, either simple strings or complex objects. Use type: list with the listType parameter to specify what kind of items the list contains.
String Lists
For lists of simple string values, use type: list with listType: string:
options:
- name: allowed_prefixes
type: list
listType: string
label: Allowed Prefixes
description: List of allowed prefix strings
default:
- income_statement___
- balance_sheet___
- cash_flow___
type: list indicates this is an arraylistType: string specifies array items are stringsdefault should be an array of strings- Users can add/remove items through the UI
Resulting value in code:
allowed_prefixes = options.get('allowed_prefixes', [])
# ['income_statement___', 'balance_sheet___', 'cash_flow___']
Object Lists
For lists of complex objects, use type: list with listType: object and define the object structure using groupOptions:
options:
- name: sections
type: list
listType: object
label: Document Sections
description: Configure sections to extract from documents
default:
- heading: Executive Summary
required: true
page_limit: 2
- heading: Financial Data
required: true
page_limit: 5
groupOptions:
- name: heading
type: string
label: Section Heading
description: The heading text to look for
required: true
- name: required
type: boolean
label: Required Section
description: Whether this section must be present
default: false
- name: page_limit
type: number
label: Maximum Pages
description: Maximum number of pages for this section
min: 1
max: 50
default: 10
type: list indicates this is an arraylistType: object specifies array items are objectsgroupOptions defines the schema for each object in the arraydefault should be an array of objects matching the schema- Each object in the default must conform to the groupOptions structure
Resulting value in code:
sections = options.get('sections', [])
# [
# {'heading': 'Executive Summary', 'required': True, 'page_limit': 2},
# {'heading': 'Financial Data', 'required': True, 'page_limit': 5}
# ]
for section in sections:
heading = section.get('heading')
is_required = section.get('required', False)
page_limit = section.get('page_limit', 10)
Nested Lists in Objects
You can nest lists within objects for complex hierarchical structures:
options:
- name: field_mappings
type: list
listType: object
label: Field Mappings
description: Define how to map source fields to target fields
groupOptions:
- name: source_field
type: string
label: Source Field Name
required: true
- name: target_field
type: string
label: Target Field Name
required: true
- name: transformations
type: list
listType: string
label: Transformations
description: List of transformations to apply
default:
- trim
- lowercase
field_mappings = options.get('field_mappings', [])
# [
# {
# 'source_field': 'CustomerName',
# 'target_field': 'customer_name',
# 'transformations': ['trim', 'lowercase', 'remove_special_chars']
# }
# ]
Object Options
Objects allow you to group related options together. Use type: object with groupOptions to define the object’s properties.
Simple Object
options:
- name: database_config
type: object
label: Database Configuration
description: Database connection settings
properties:
collapsible: true
groupOptions:
- name: host
type: string
label: Database Host
default: localhost
required: true
- name: port
type: number
label: Database Port
default: 5432
min: 1
max: 65535
- name: database_name
type: string
label: Database Name
required: true
- name: use_ssl
type: boolean
label: Use SSL Connection
default: true
type: object indicates this is a structured objectgroupOptions defines the properties of the objectproperties.collapsible: true makes the group collapsible in the UI- Each property in
groupOptions follows the same option structure
Resulting value in code:
db_config = options.get('database_config', {})
host = db_config.get('host', 'localhost')
port = db_config.get('port', 5432)
database_name = db_config.get('database_name')
use_ssl = db_config.get('use_ssl', True)
Nested Objects
Objects can contain other objects for deep hierarchical structures:
options:
- name: api_config
type: object
label: API Configuration
groupOptions:
- name: authentication
type: object
label: Authentication Settings
groupOptions:
- name: method
type: select
label: Auth Method
possibleValues:
- label: API Key
value: api_key
- label: OAuth 2.0
value: oauth2
- name: api_key
type: string
label: API Key
password: true
showIf: "this.api_config.authentication.method === 'api_key'"
- name: oauth_settings
type: object
label: OAuth Settings
showIf: "this.api_config.authentication.method === 'oauth2'"
groupOptions:
- name: client_id
type: string
label: Client ID
- name: client_secret
type: string
label: Client Secret
password: true
Default Value Structures
Default values must match the type structure:
| Type | Default Value Structure | Example |
|---|
string | Single string value | default: "localhost" |
text | Single string (can be multiline) | default: "Line 1\nLine 2" |
number | Single numeric value | default: 5432 |
boolean | Single boolean value | default: true |
select | Single value from possibleValues | default: "json" |
list (string) | Array of strings | default: ["item1", "item2"] |
list (object) | Array of objects | default: [{name: "val"}] |
object | Object with properties | default: {host: "localhost"} |
Examples of Correct Default Values
# String - single value
- name: hostname
type: string
default: "localhost"
# Number - single value
- name: port
type: number
default: 5432
# Boolean - single value
- name: enabled
type: boolean
default: true
# Select - single value (must match a possibleValue)
- name: format
type: select
default: "json"
possibleValues:
- label: JSON
value: json
- label: CSV
value: csv
# List of strings - array of strings
- name: tags
type: list
listType: string
default:
- production
- verified
- active
# List of objects - array of objects
- name: endpoints
type: list
listType: object
default:
- url: "https://api1.example.com"
timeout: 30
- url: "https://api2.example.com"
timeout: 60
groupOptions:
- name: url
type: string
- name: timeout
type: number
# Object - object with properties
- name: connection
type: object
default:
host: "localhost"
port: 5432
ssl: true
groupOptions:
- name: host
type: string
- name: port
type: number
- name: ssl
type: boolean
Anti-Patterns to Avoid
❌ DON’T: Use text fields for lists
# WRONG - Using multiline text for what should be a list
- name: allowed_values
type: text
lines: 5
default: |
- value1
- value2
- value3
✅ DO: Use proper list type
# CORRECT - Use type: list with listType
- name: allowed_values
type: list
listType: string
default:
- value1
- value2
- value3
- Lists provide structured data that’s easy to validate
- Users get proper UI controls (add/remove buttons)
- Code receives properly typed arrays, not strings that need parsing
- Validation and error handling are automatic
❌ DON’T: Use text for structured data
# WRONG - Using text for object-like data
- name: config
type: text
default: |
host: localhost
port: 5432
ssl: true
✅ DO: Use object type
# CORRECT - Use type: object with groupOptions
- name: config
type: object
groupOptions:
- name: host
type: string
default: localhost
- name: port
type: number
default: 5432
- name: ssl
type: boolean
default: true
❌ DON’T: Mix default value structure with type
# WRONG - Default doesn't match list type
- name: items
type: list
listType: string
default: "item1,item2,item3" # Should be an array!
✅ DO: Match default structure to type
# CORRECT - Default is an array matching listType
- name: items
type: list
listType: string
default:
- item1
- item2
- item3
Real-World Example: Comprehensive Configuration
Here’s a complete example showing lists, objects, and nesting:
options:
- name: processing_config
type: object
label: Processing Configuration
groupOptions:
# String list
- name: allowed_file_types
type: list
listType: string
label: Allowed File Types
description: File extensions to process
default:
- pdf
- docx
- txt
# Object with nested settings
- name: validation_rules
type: object
label: Validation Rules
properties:
collapsible: true
groupOptions:
- name: min_file_size
type: number
label: Minimum File Size (KB)
default: 1
min: 0
- name: max_file_size
type: number
label: Maximum File Size (MB)
default: 50
min: 1
max: 500
# List of objects
- name: extraction_rules
type: list
listType: object
label: Extraction Rules
description: Define rules for extracting data
default:
- field_name: invoice_number
pattern: "INV-\\d{6}"
required: true
- field_name: date
pattern: "\\d{4}-\\d{2}-\\d{2}"
required: true
groupOptions:
- name: field_name
type: string
label: Field Name
required: true
- name: pattern
type: string
label: Regex Pattern
description: Regular expression pattern to match
required: true
- name: required
type: boolean
label: Required Field
default: false
- name: transformations
type: list
listType: string
label: Transformations
description: Post-extraction transformations
default:
- trim
- uppercase
def __init__(self, options):
# Get the processing config object
config = options.get('processing_config', {})
# Get string list
allowed_types = config.get('allowed_file_types', [])
# ['pdf', 'docx', 'txt']
# Get nested object
validation = config.get('validation_rules', {})
min_size = validation.get('min_file_size', 1)
max_size = validation.get('max_file_size', 50)
# Get object list
extraction_rules = config.get('extraction_rules', [])
for rule in extraction_rules:
field = rule.get('field_name')
pattern = rule.get('pattern')
required = rule.get('required', False)
transforms = rule.get('transformations', [])
# Process each rule
self.add_extraction_rule(field, pattern, required, transforms)
Option Groups
Options can be nested into groups for better organization and user experience:
options:
- name: database_settings
type: object
label: Database Settings
description: Configure database connection
properties:
collapsible: true
groupOptions:
- name: host
type: string
label: Database Host
required: true
default: "localhost"
- name: port
type: number
label: Database Port
default: 5432
- name: database_name
type: string
label: Database Name
required: true
- name: use_ssl
type: boolean
label: Use SSL Connection
default: true
- Organizes related options together
- Can be made collapsible to reduce UI clutter
- Creates a hierarchy of configuration
- Improves user experience for complex configurations
Properties for groups:
collapsible: true - Makes the group expandable/collapsible in the UI
Providing Possible Values
Limit user input to specific choices using possibleValues:
- name: output_format
type: string
label: Output Format
description: The format of the exported data
possibleValues:
- label: JSON
value: json
- label: CSV
value: csv
- label: Excel Spreadsheet
value: xlsx
- label: XML
value: xml
default: json
Conditional Visibility
Use showIf to show/hide options based on other values:
options:
- name: use_authentication
type: boolean
label: Require Authentication
default: false
- name: username
type: string
label: Username
showIf: "this.use_authentication === true"
- name: password
type: string
label: Password
password: true
showIf: "this.use_authentication === true"
username and password options only appear when use_authentication is checked.
showIf syntax:
- JavaScript expression evaluated against current option values
- Access other options via
this.optionName
- Supports boolean logic:
&&, ||, !
- Comparison operators:
===, !==, >, <, >=, <=
Complex example:
- name: deployment_type
type: select
label: Deployment Type
possibleValues:
- label: Cloud
value: cloud
- label: On-Premise
value: on_premise
- name: cloud_region
type: select
label: Cloud Region
showIf: "this.deployment_type === 'cloud'"
possibleValues:
- label: US East
value: us_east
- label: EU West
value: eu_west
- name: server_address
type: string
label: Server Address
showIf: "this.deployment_type === 'on_premise'"
Developer-Only Options
Hide advanced options from regular users:
- name: debug_logging
type: boolean
label: Enable Debug Logging
description: Output detailed debug logs
developerOnly: true
default: false
developerOnly: true are only visible to users who have enabled “Show Developer Tools” in their settings.
Feature Flags
Gate options behind feature flags:
- name: experimental_feature
type: boolean
label: Enable Experimental Feature
description: Try out our new experimental feature
featureFlag: experimental_features
default: false
Common Option Properties
All options support these common properties:
| Property | Type | Description | Required |
|---|
name | string | Unique identifier for the option | Yes |
type | string | Option type (determines UI control) | Yes |
label | string | User-facing display name | Yes |
description | string | Help text explaining the option | Yes |
required | boolean | Whether the value is mandatory | No (default: false) |
default | any | Pre-filled default value | No |
possibleValues | array | Allowed values (for select types) | No |
showIf | string | JavaScript expression for conditional visibility | No |
developerOnly | boolean | Only show to developers | No (default: false) |
featureFlag | string | Feature flag that must be enabled | No |
properties | object | Additional metadata (e.g., collapsible) | No |
Best Practices
1. Provide Clear Labels and Descriptions
# Good
- name: max_retries
label: Maximum Retry Attempts
description: Number of times to retry failed operations before giving up. Set to 0 to disable retries.
# Poor
- name: max_retries
label: Retries
description: Max retries
2. Use Appropriate Types
Match the option type to the kind of data you’re collecting:
# Good
- name: port
type: number
min: 1
max: 65535
# Poor
- name: port
type: string
list and object types instead of text fields. See the Anti-Patterns section in “Working with Lists and Objects” for detailed examples.
3. Set Sensible Defaults
- name: timeout
type: number
label: Request Timeout (seconds)
description: How long to wait for a response
default: 30 # Most users won't need to change this
min: 1
max: 300
- name: connection_settings
type: object
label: Connection Settings
properties:
collapsible: true
groupOptions:
- name: host
type: string
- name: port
type: number
- name: timeout
type: number
5. Use Required Judiciously
Only mark options as required: true if the component truly cannot function without them:
- name: api_key
type: string
label: API Key
required: true # Cannot work without this
- name: log_level
type: select
label: Log Level
required: false # Has a default
default: info
6. Leverage Conditional Visibility
Keep the UI clean by hiding irrelevant options:
- name: use_proxy
type: boolean
label: Use HTTP Proxy
default: false
- name: proxy_url
type: string
label: Proxy URL
showIf: "this.use_proxy === true"
- name: proxy_username
type: string
label: Proxy Username
showIf: "this.use_proxy === true"
Using Options in Code
Python (Assistants/Modules)
class MyAssistant:
def __init__(self, options):
# Options are passed as a dictionary
self.hostname = options.get('hostname')
self.port = options.get('port', 22) # With default
self.use_ssl = options.get('use_ssl', False)
# Nested options from groups
db_settings = options.get('database_settings', {})
self.db_host = db_settings.get('host', 'localhost')
self.db_port = db_settings.get('port', 5432)
def run(self, context):
# Use the configured values
connection = connect(
host=self.hostname,
port=self.port,
ssl=self.use_ssl
)
Validation Example
def __init__(self, options):
# Validate required options
if 'api_key' not in options:
raise ValueError("api_key is required")
# Validate value ranges
timeout = options.get('timeout', 30)
if timeout < 1 or timeout > 300:
raise ValueError("timeout must be between 1 and 300")
self.api_key = options['api_key']
self.timeout = timeout
Summary
Options are Kodexa’s declarative configuration system. By defining options in metadata, you:
- Enable user configuration without writing UI code
- Provide type-safe input with automatic validation
- Create consistent experiences across all components
- Capture custom information tailored to your needs
- Keep configuration co-located with component definitions
The Options system supports 24+ different types, from simple text inputs to complex taxonomy selectors with nested properties. Master options to build flexible, user-configurable components that integrate seamlessly into the Kodexa platform.
