Skip to main content

​
Options Architecture

The Options system is a foundational feature in Kodexa that enables developers to define flexible, type-safe configuration interfaces throughout the platform. Options provide a declarative way to capture custom information from users while maintaining consistency across all components.

​
What Are Options?

Options are configuration parameters that allow you to:
  • Capture user input in a structured, validated way
  • Define custom properties for components (assistants, models, steps)
  • Add configurable fields to taxonomies (data elements)
  • Create dynamic form interfaces without writing UI code
  • Enable users to configure components directly in the platform UI
Think of options as a schema language for user configuration - you describe what you need, and Kodexa automatically generates the appropriate UI controls and validation.

​
The Options Flow

Developer defines options → Platform generates UI → User configures → Values passed to code
     (in metadata)           (automatically)         (in UI)          (at runtime)

​
Example: Simple Assistant with Options

Developer defines (in assistant metadata): 
options:
  - name: hostname
    type: string
    label: SFTP Hostname
    description: The hostname of the SFTP server
    required: true
  - name: port
    type: number
    label: Port
    description: Port number for SFTP connection
    default: 22
Platform generates: Text input field + numeric input field with validation User configures: Enters “sftp.example.com” and “2222” Code receives: {'hostname': 'sftp.example.com', 'port': 2222}

​
Where Are Options Used?

Options appear throughout the Kodexa platform:

​
1. Assistants

Define configuration parameters for assistant behavior: 
- slug: data-publisher
  type: assistant
  options:
    - name: schedule
      type: string
      label: Publication Schedule
    - name: format
      type: select
      possibleValues:
        - label: JSON
          value: json
        - label: CSV
          value: csv

​
2. Models

Configure inference and training behavior: 
metadata:
  type: model
  inferOptions:
    - name: confidence_threshold
      type: number
      label: Confidence Threshold
      default: 0.85
      description: Minimum confidence score for predictions
  trainOptions:
    - name: epochs
      type: number
      label: Training Epochs
      default: 10

​
3. Taxonomies (Data Definitions)

Add custom properties to data elements: 
taxons:
  - label: Invoice
    path: /invoice
    options:
      - name: required
        type: boolean
        label: Required Field
        default: false
      - name: validation_rule
        type: select
        label: Validation Rule
        possibleValues:
          - label: None
            value: none
          - label: Numeric Only
            value: numeric
          - label: Date Format
            value: date
When users label documents, they can set these properties on each labeled instance.

​
4. Actions

Configure executable actions: 
- slug: send-email
  type: action
  options:
    - name: recipient
      type: string
      label: Email Recipient
      required: true
    - name: subject
      type: string
      label: Subject Line

​
5. Pipeline Steps

Configure processing steps in pipelines: 
steps:
  - stepRef: normalize-text
    options:
      - name: lowercase
        type: boolean
        default: true
      - name: remove_punctuation
        type: boolean
        default: false

​
Core Option Structure

Every option has this basic structure: 
- name: option_name           # Key used to access the value in code
  type: string                # Option type (determines UI control)
  label: Display Name         # Shown to users
  description: Help text      # Explains what this option does
  required: false             # Whether value is mandatory
  default: default_value      # Pre-filled value

​
Required Fields

  • name: Unique identifier for the option (used in code to access the value)
  • type: Determines which UI control to render and how to validate input
  • label: User-facing display name
  • description: Help text explaining the purpose and usage

​
Optional Fields

  • required: Boolean indicating if the option must be set (default: false)
  • default: Pre-filled value shown to users
  • possibleValues: Array of allowed values (for dropdowns/selects)
  • showIf: Conditional visibility based on other option values
  • developerOnly: Only show to users with developer privileges
  • featureFlag: Gate option behind a feature flag
  • properties: Additional metadata for option behavior (e.g., collapsible: true)

​
Option Types Overview

Kodexa supports 24+ option types organized into categories:

​
Basic Input Types

  • string / text: Single or multi-line text input
  • number: Numeric input with optional min/max constraints
  • boolean: Checkbox or toggle switch
  • select: Dropdown selection from predefined values

​
Code & Script Types

  • code: Full code editor with syntax highlighting
  • script: Script input (supports multiple languages)

​
Platform-Specific Types

  • documentStore: Select a document store
  • modelStore: Select a model store
  • tableStore: Select a data store
  • taxonomyStore: Select a taxonomy (data definition)
  • document: Search and select a specific document
  • workspace: Select a workspace

​
Taxonomy Types

  • taxon: Select a taxonomy element
  • taxon_label: Select a taxonomy label
  • taxon_with_properties: Select taxonomy + configure properties
  • taxon-lookup: Hierarchical taxonomy search

​
Status & State Types

  • documentStatus: Select document status
  • attributeStatus: Select attribute status
  • taskStatus: Select task status

​
Advanced Types

  • cloud-model: Select cloud-based AI model (with caching)
  • cloud-embedding: Select embedding model
  • pipeline: Configure entire pipeline
  • pipelineModelOptions: Configure multiple models in pipeline
  • data-form: Select data form configuration

​
Display Types

  • alert: Display informational message
  • article: Embed knowledge base article

​
Nested Options (Option Groups)

Options can be nested into groups for better organization: 
options:
  - name: connection_settings
    type: object
    label: Connection Settings
    description: Database connection configuration
    properties:
      collapsible: true  # Can be collapsed in UI
    groupOptions:
      - name: host
        type: string
        label: Database Host
        required: true
      - name: port
        type: number
        label: Database Port
        default: 5432
      - name: use_ssl
        type: boolean
        label: Use SSL
        default: true
This creates a collapsible section containing three related options.

​
Conditional Visibility

Use showIf to show/hide options based on other values: 
options:
  - name: use_custom_endpoint
    type: boolean
    label: Use Custom Endpoint
    default: false

  - name: endpoint_url
    type: string
    label: Custom Endpoint URL
    showIf: "this.use_custom_endpoint === true"
    # Only shown when use_custom_endpoint is checked
The showIf field accepts JavaScript expressions evaluated against the current option values.

​
Possible Values (Constrained Choices)

Limit user input to predefined choices: 
- name: output_format
  type: string
  label: Output Format
  description: Format for exported data
  possibleValues:
    - label: JSON
      value: json
    - label: CSV
      value: csv
    - label: XML
      value: xml
Renders as a dropdown with only these three options.

​
Developer-Only Options

Hide advanced options from regular users: 
- name: debug_mode
  type: boolean
  label: Enable Debug Logging
  developerOnly: true  # Only visible to users with "Show Developer Tools" enabled

​
Accessing Option Values in Code

​
In Python (Assistants/Models)

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)

    def run(self, context):
        # Use the configured values
        connection = connect(
            host=self.hostname,
            port=self.port,
            ssl=self.use_ssl
        )

​
In Metadata (Other Components)

Options can reference each other or be used in expressions: 
pipeline:
  steps:
    - stepRef: process-documents
      options:
        input_store: ${parent.options.source_store}  # Reference parent option

​
Best Practices

​
1. Provide Clear Labels and Descriptions

# Good
- name: retry_count
  label: Maximum Retry Attempts
  description: Number of times to retry failed operations before giving up

# Poor
- name: retry_count
  label: Retry Count
  description: Retries

​
2. Use Appropriate Types

# Good - type matches the data
- name: port
  type: number

# Poor - storing number as string
- name: port
  type: string

​
3. Set Sensible Defaults

- name: timeout
  type: number
  label: Request Timeout (seconds)
  default: 30  # Most users won't need to change this

- name: email_settings
  type: object
  label: Email Configuration
  groupOptions:
    - name: smtp_host
      type: string
    - name: smtp_port
      type: number
    - name: use_tls
      type: boolean

​
5. Use required Judiciously

Only mark options as required if the component truly cannot function without them. 
- name: api_key
  type: string
  label: API Key
  required: true  # Component cannot work without this

- name: log_level
  type: select
  label: Log Level
  required: false  # Has a reasonable default
  default: info

​
6. Leverage Conditional Visibility

Keep the UI clean by hiding irrelevant options: 
- name: use_proxy
  type: boolean
  label: Use HTTP Proxy

- name: proxy_url
  type: string
  label: Proxy URL
  showIf: "this.use_proxy === true"

- name: proxy_auth
  type: boolean
  label: Proxy Requires Authentication
  showIf: "this.use_proxy === true"

​
How Options Enable Custom Information Capture

The Options system is powerful because it provides declarative configuration:
  1. No UI Code Required: Define options in YAML, get a UI automatically
  2. Type Safety: Platform validates input based on option type
  3. Consistency: Same option types look and behave the same everywhere
  4. Discoverability: Users see configuration options in context
  5. Versioning: Options are part of component metadata (versioned with the component)

​
Example: Custom Data Capture

Suppose you’re building a custom invoice extraction model. You want users to configure:
  • Which fields are required
  • Validation rules per field
  • Output format preferences
Without options, you’d need to:
  1. Build a custom UI
  2. Handle validation
  3. Store configuration somewhere
  4. Pass configuration to your model code
With options, you simply: 
metadata:
  type: model
  inferOptions:
    - name: required_fields
      type: taxon_with_properties
      label: Required Fields
      description: Mark which invoice fields must be present

    - name: validation_rules
      type: object
      label: Validation Rules
      groupOptions:
        - name: validate_dates
          type: boolean
          default: true
        - name: validate_amounts
          type: boolean
          default: true

    - name: output_format
      type: select
      label: Output Format
      possibleValues:
        - label: JSON
          value: json
        - label: Structured CSV
          value: csv
Kodexa generates the UI, validates input, and passes the configuration to your model.

​
Next Steps

​
Summary

The Options system is Kodexa’s declarative configuration language. By defining options in metadata, you:
  • Enable users to configure your components without code changes
  • Provide a consistent, validated configuration experience
  • Capture custom information tailored to your use case
  • Keep configuration co-located with component definitions
Options turn configuration from a UI development task into a metadata declaration, allowing you to focus on building functionality rather than forms.