Habit Schema
Workflows in Habits define automation sequences by connecting nodes that execute in order.
Full Schema
yaml
$schema: http://json-schema.org/draft-07/schema#
definitions:
Record<string,any>:
type: object
# Application configuration for desktop/mobile builds (used in stack.yaml)
ApplicationConfig:
type: object
description: |
Application configuration for desktop/mobile builds.
Used to configure Tauri apps with OAuth deep link support.
properties:
scheme:
type: string
description: |
Custom URL scheme for OAuth deep links.
Example: "myapp" creates URLs like myapp://oauth/callback
Required for OAuth authentication in Tauri desktop/mobile apps.
name:
type: string
description: Application display name (used in Tauri builds)
identifier:
type: string
description: |
Application identifier (e.g., "com.mycompany.myapp").
Used for bundle identifiers on iOS/macOS and package names on Android.
# Logging configuration for workflow-level or stack-level logging
LogLevel:
type: string
enum:
- trace
- debug
- info
- warn
- error
- fatal
- none
description: |
Log level for filtering messages.
trace: Most verbose, for detailed debugging
debug: Debugging information
info: General information (default)
warn: Warnings, potential issues
error: Errors, failures
fatal: Critical errors, system failures
none: Disable all logging
LoggingConfig:
type: object
description: |
Logging configuration. Can be specified in habit.yaml (per-workflow) or stack.yaml (global).
Environment variables override all config (HABITS_LOG_LEVEL, HABITS_LOG_OUTPUT, etc.)
properties:
level:
$ref: "#/definitions/LogLevel"
description: Default log level for all loggers
default: info
outputs:
type: array
items:
type: string
enum:
- console
- file
- json
description: Output destinations (console, file, json)
default: [console]
file:
type: object
description: File output configuration (only used if 'file' is in outputs)
properties:
path:
type: string
description: Path to log file
default: ./logs/habits.log
maxSize:
type: string
description: Maximum file size before rotation (e.g., '10mb', '1gb')
default: 10mb
maxFiles:
type: integer
description: Maximum number of rotated files to keep
default: 5
minimum: 1
format:
type: string
enum:
- text
- json
description: Output format for console/file
default: text
colorize:
type: boolean
description: Enable ANSI colors in console output (auto-detected if not specified)
bitOverrides:
type: object
description: |
Per-bit log level overrides. Keys are bit names (e.g., 'bit-http', 'bit-openai').
Values are log levels.
additionalProperties:
$ref: "#/definitions/LogLevel"
# ============================================================
# Workflow Input/Output/Env Schema Types
# Types for defining workflow inputs, outputs, and environment variables
# with rich type information for auto-generating mobile UIs.
# ============================================================
# Data types for workflow fields
FieldType:
type: string
enum:
- string # Plain text
- number # Numeric value (integer or float)
- boolean # True/false checkbox
- object # JSON object
- array # JSON array
- json # Arbitrary JSON (alias for object)
- base64 # Base64-encoded binary data
- file # File upload/path
- email # Email address (string with validation)
- url # URL (string with validation)
- date # Date string (ISO 8601)
- time # Time string
- datetime # DateTime string (ISO 8601)
- secret # Sensitive value (masked in UI, stored securely)
description: |
Data type for workflow input/output/env fields.
Used for validation and to determine appropriate UI controls.
# UI display hints for input fields
InputDisplayAs:
type: string
enum:
- text # Single-line text input
- textarea # Multi-line text input
- number # Numeric input with spinner
- checkbox # Boolean toggle/checkbox
- dropdown # Select from options
- radio # Radio button group
- file-picker # File selection dialog
- date-picker # Date picker calendar
- time-picker # Time picker
- datetime-picker # Combined date/time picker
- password # Masked text input for secrets
- json-editor # JSON editor with syntax highlighting
- code-editor # Code editor (for scripts)
description: |
UI control type for rendering input fields.
If not specified, inferred from field type.
# UI display hints for output fields
OutputDisplayAs:
type: string
enum:
- text # Plain text display
- json # JSON tree viewer
- markdown # Rendered markdown
- image # Display as image (for base64/URLs)
- download # Download link
- code # Syntax-highlighted code block
- table # Table view for arrays
- hidden # Don't display (internal use)
description: |
UI display type for rendering output values.
If not specified, inferred from field type.
# Validation constraints for input fields
FieldValidation:
type: object
description: Validation rules for input fields
properties:
min:
type: number
description: Minimum value (for numbers) or minimum length (for strings)
max:
type: number
description: Maximum value (for numbers) or maximum length (for strings)
pattern:
type: string
description: Regex pattern for string validation
minLength:
type: integer
description: Minimum string length
maxLength:
type: integer
description: Maximum string length
minItems:
type: integer
description: Minimum array items
maxItems:
type: integer
description: Maximum array items
# Dropdown/radio option definition
FieldOption:
type: object
required:
- value
properties:
value:
description: The actual value to use
label:
type: string
description: Display label (defaults to value if not specified)
description:
type: string
description: Optional description shown as hint
# Workflow input field definition
WorkflowInputField:
type: object
required:
- id
properties:
id:
type: string
description: Field identifier, used as key in workflow input object
type:
$ref: "#/definitions/FieldType"
description: Data type (default: string)
default: string
displayAs:
$ref: "#/definitions/InputDisplayAs"
description: UI control type (inferred from type if not specified)
displayName:
type: string
description: Human-readable label shown in UI (defaults to id)
description:
type: string
description: Help text shown below the input field
required:
type: boolean
description: Whether this field is required
default: false
default:
description: Default value if not provided
placeholder:
type: string
description: Placeholder text shown in empty input
options:
type: array
items:
$ref: "#/definitions/FieldOption"
description: Options for dropdown/radio fields
validation:
$ref: "#/definitions/FieldValidation"
description: Validation constraints
dependsOn:
type: string
description: ID of another field this field depends on (for conditional visibility)
showIf:
type: string
description: Expression to evaluate for conditional visibility (e.g., "otherField === 'yes'")
# Workflow output field definition
WorkflowOutputField:
type: object
required:
- id
- value
properties:
id:
type: string
description: Output field identifier
value:
type: string
description: Template expression referencing a node output (e.g., "{{node-id}}" or "{{node-id.field}}")
type:
$ref: "#/definitions/FieldType"
description: Data type of the output (for UI rendering hints)
default: string
displayAs:
$ref: "#/definitions/OutputDisplayAs"
description: How to render this output in the UI
displayName:
type: string
description: Human-readable label shown in UI (defaults to id)
description:
type: string
description: Description of what this output represents
# Workflow environment variable definition
WorkflowEnvField:
type: object
required:
- id
properties:
id:
type: string
description: |
Environment variable name (without HABITS_ prefix).
Referenced in workflow as {{habits.env.ID}}
type:
$ref: "#/definitions/FieldType"
description: Data type (default: string)
default: string
displayName:
type: string
description: Human-readable label shown in settings UI
description:
type: string
description: Help text explaining what this env var is used for
required:
type: boolean
description: Whether this env var is required for workflow execution
default: false
secret:
type: boolean
description: |
If true, value is stored in system keyring (secure storage)
and masked in UI. Use for API keys, passwords, tokens.
default: false
default:
type: string
description: Default value if not set (not recommended for secrets)
WorkflowEdge:
type: object
properties:
id:
type: string
source:
type: string
sourceHandle:
type: string
target:
type: string
targetHandle:
type: string
WorkflowNode:
type: object
properties:
id:
type: string
type:
type: string
enum:
- action
- trigger
- script
- bit # Custom bits (see roadmap/bits.md) - includes declarative, moderation, and other bit subtypes
position:
type: object
properties:
x:
type: number
y:
type: number
data:
type: object
properties:
label:
type: string
framework:
type: string
enum:
- script
- bits # Custom bits framework (see roadmap/bits.md)
module:
type: string
operation:
type: string
description: |
Which action/function to execute in the bit module.
Maps to a specific function exported by the bit (e.g., 'install_model', 'query', 'sendEmail').
Required when a bit exposes multiple operations.
Also used for filtering which input parameters are shown in the UI via displayOptions.show.operation.
source:
type: string
description: Module source - 'npm' or 'github'
enum:
- npm
- github
registry:
type: string
description: |
Custom npm registry URL for 'npm' source modules.
If not provided, uses HABITS_NPM_REGISTRY_URL environment variable,
or defaults to https://registry.npmjs.org.
Useful for private registries like Verdaccio.
isCue:
type: boolean
description: Marks this node as a cue (entry point) for the workflow. A cue triggers the workflow to start.
isTrigger:
type: boolean
description: (Deprecated) Use isCue instead. Marks this node as an entry point for the workflow.
deprecated: true
inputs:
type: array
items:
type: string
outputs:
type: array
items:
type: string
inputTransforms:
$ref: "#/definitions/Record<string,any>"
credentials:
$ref: "#/definitions/Record<string,any>"
params:
type: object
additionalProperties: true
properties:
type:
type: string
description: Type parameter - 'script'
language:
type: string
enum:
- bash
- deno
- go
- python3
- sql
- typescript
description: Script language for script framework nodes
script:
type: string
description: The script code for script framework nodes
stopAfterIf:
type: object
properties:
expr:
type: string
skipIfStopped:
type: boolean
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
version:
type: string
# Workflow input schema - defines expected inputs with types and UI hints
input:
type: array
items:
$ref: "#/definitions/WorkflowInputField"
description: |
Workflow input field definitions.
Defines the inputs the workflow expects with types, validation, and UI hints.
Used to auto-generate mobile UI forms.
Example:
input:
- id: email
type: email
displayName: Email Address
required: true
- id: message
type: string
displayAs: textarea
description: Your message
# Environment variable declarations
env:
type: array
items:
$ref: "#/definitions/WorkflowEnvField"
description: |
Environment variable declarations.
Explicitly declares env vars the workflow needs (referenced as {{habits.env.ID}}).
Used to auto-generate settings UI and prompt for missing values.
Example:
env:
- id: OPENAI_API_KEY
displayName: OpenAI API Key
secret: true
required: true
- id: DEBUG_MODE
type: boolean
default: "false"
nodes:
type: array
items:
$ref: "#/definitions/WorkflowNode"
edges:
type: array
items:
$ref: "#/definitions/WorkflowEdge"
# Workflow output schema - supports both legacy object format and new array format
output:
oneOf:
- type: object
description: |
Legacy output mapping (key-value pairs).
Keys are output names, values are template expressions.
additionalProperties:
type: string
- type: array
items:
$ref: "#/definitions/WorkflowOutputField"
description: |
New output field definitions with type hints.
Allows specifying output types and UI display hints.
description: |
Workflow output mapping.
Can be either:
1. Legacy format (object): Simple key-value mapping
output:
result: "{{node-id}}"
2. New format (array): Rich output definitions with types
output:
- id: result
value: "{{node-id}}"
type: json
displayAs: json
logging:
$ref: "#/definitions/LoggingConfig"
description: |
Per-workflow logging configuration (optional).
Overridden by stack.yaml logging config, which is overridden by environment variables.Workflow Structure
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier for the workflow |
name | string | Yes | Human-readable name |
description | string | No | Workflow description |
inputs | object | No | Input parameters with types and defaults |
nodes | array | Yes | List of node definitions |
edges | array | Yes | Node connections defining execution flow |
output | object | No | Output mapping for workflow results |
Nodes
Each node represents a single operation in your workflow.
Node Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the node |
type | string | script or bit |
position | object | Optional { x, y } coordinates for visual layout |
data | object | Node configuration (see below) |
Node Data Fields
| Field | Type | Description |
|---|---|---|
label | string | Display name for the node |
framework | string | script or bits |
module | string | Module/package name (e.g., @ha-bits/bit-openai) |
operation | string | Operation to execute |
source | string | Module source (npm, inline) |
isTrigger | boolean | Marks node as workflow entry point |
params | object | Operation parameters |
credentials | object | Authentication credentials |
inputTransforms | object | Input data transformations |
stopAfterIf | object | Conditional stop with expr and skipIfStopped |
Script Params
For type: script nodes:
| Field | Type | Description |
|---|---|---|
type | string | Set to "script" |
language | string | bash, deno, go, python3, sql, or typescript |
script | string | The script code to execute |
Edges
Edges define how data flows between nodes.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Unique identifier for the edge |
source | string | Yes | ID of the source node |
target | string | Yes | ID of the target node |
sourceHandle | string | No | Output handle on source node |
targetHandle | string | No | Input handle on target node |
Data References
Reference data from other nodes using template syntax:
| Pattern | Description |
|---|---|
{{<nodeId>}} | Full output from a specific node |
{{<nodeId>.<path>}} | Nested property from node output (JSON) |
{{habits.env.<VAR>}} | Environment variable |
{{habits.input.<field>}} | Runtime input parameter |
{{habits.header.<header>}} | Request header |
{{habits.cookies.<cookie>}} | Request cookie |
Stack Configuration
The stack.yaml file defines workflows and server settings:
| Field | Type | Description |
|---|---|---|
version | string | Config version |
workflows | array | Workflow paths or inline definitions |
server.port | number | Server port (default: 3000) |
server.host | string | Server host (default: 0.0.0.0) |
logging | object | Logging configuration |
Next Steps
- Creating Habits - Build workflows visually or as code
- Running Automations - Execute and monitor workflows
- Showcase - Browse complete showcase