> ## 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.

# Project Template Structure Reference

> Reference for activity-first Kodexa project template structure: stores, data definitions, task templates, forms, statuses, and workspace config.

A `ProjectTemplate` is a metadata blueprint for creating a repeatable project workspace. It should define the resources a project needs to run a business process, while Activity Plans define the automated process itself.

## Top-Level Shape

```yaml theme={null}
slug: invoice-operations
orgSlug: acme
version: 1.0.0
name: Invoice Operations
type: projectTemplate
description: Workspace setup for invoice intake, review, and posting

stores: []
taxonomies: []
dataForms: []
taskTemplates: []
documentStatuses: []
taskStatuses: []
attributeStatuses: []
knowledgeSets: []
workspaces: []
options: {}
tags: []
```

| Field         | Required | Description                     |
| ------------- | -------- | ------------------------------- |
| `slug`        | Yes      | Stable template slug            |
| `orgSlug`     | Yes      | Owning organization slug        |
| `version`     | Yes      | Template version                |
| `name`        | Yes      | Display name                    |
| `type`        | Yes      | Must be `projectTemplate`       |
| `description` | No       | Human-readable purpose          |
| `helpUrl`     | No       | Link to implementation guidance |
| `tags`        | No       | Search and categorization tags  |

## Variable Substitution

Templates can use project and organization variables in slugs, names, descriptions, and references.

| Variable          | Description          |
| ----------------- | -------------------- |
| `${project.id}`   | Unique project ID    |
| `${project.name}` | Project display name |
| `${project.slug}` | Project slug         |
| `${orgSlug}`      | Organization slug    |

Use `${project.id}` for resources that must be unique across projects.

```yaml theme={null}
stores:
  - slug: "${project.id}-intake"
    name: "${project.name} Intake"
```

## Stores

Stores define where documents and structured data live.

```yaml theme={null}
stores:
  - slug: "${project.id}-intake"
    name: "Intake"
    description: "Incoming documents"
    storeType: DOCUMENT
    storePurpose: OPERATIONAL
    deleteProtection: true
```

| Field                | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `slug`               | Store slug                                              |
| `name`               | Display name                                            |
| `description`        | Purpose shown to users                                  |
| `storeType`          | Usually `DOCUMENT` for document workflows               |
| `storePurpose`       | `OPERATIONAL`, `TRAINING`, or another supported purpose |
| `deleteProtection`   | Prevent accidental deletion                             |
| `documentProperties` | Optional metadata fields for document families          |

## Data Definitions

Use `taxonomies` to create or reference the Data Definitions used by extracted data and Data Forms.

```yaml theme={null}
taxonomies:
  - ref: "acme/invoice"
```

Prefer references for shared business schemas. Create inline definitions only when the template owns the schema lifecycle.

## Task Templates

Task Templates define human work that Activity Plans can create with `CREATE_TASK` steps.

```yaml theme={null}
taskTemplates:
  - slug: invoice-review
    name: Invoice Review
    description: Review extracted invoice fields and resolve exceptions
    taskType: REVIEW
```

Use Task Templates for queue assignment, review intent, task metadata, and links to the forms reviewers need.

## Data Forms

Data Forms provide the structured review UI for extracted data.

```yaml theme={null}
dataForms:
  - ref: "acme/invoice-review-form"
```

Bind forms to the Data Definitions they review. Keep form definitions reusable when several projects share the same review experience.

## Statuses

Project templates can define document, task, and attribute statuses. Use statuses to make the workflow observable to operators.

```yaml theme={null}
taskStatuses:
  - slug: ready-for-review
    label: Ready for Review
    statusType: TODO
    color: "#3B82F6"

  - slug: complete
    label: Complete
    statusType: DONE
    locked: true
    color: "#10B981"
```

Task statuses with status type `DONE` are important for Activity choreography: script and task status changes can advance downstream Activity work.

## Knowledge Sets

Knowledge Sets provide reusable classifications, reference data, and extraction context.

```yaml theme={null}
knowledgeSets:
  - ref: "acme/supplier-reference"
  - ref: "acme/invoice-document-types"
```

Use Knowledge Sets when a workflow should reuse business knowledge across projects instead of embedding that knowledge in scripts or forms.

## Workspace Configuration

Workspaces control the operator surface for a project. Enable only the panels the process needs.

```yaml theme={null}
workspaces:
  - name: Operations Workspace
    slug: operations
    workspaceStorage:
      availablePanels:
        documentStores: true
        dataForms: true
        taxonomies: true
        exceptions: true
        auditEvents: true
        navigation: true
      overview: |-
        # Operations Workspace

        Upload documents, review extracted data, and resolve exceptions.
```

Common panels include `documentStores`, `dataForms`, `taxonomies`, `properties`, `exceptions`, `auditEvents`, `navigation`, and `channels`.

## Options

Use options for project-level configuration that must vary between projects.

```yaml theme={null}
options:
  options:
    - name: confidence_threshold
      type: number
      label: Confidence Threshold
      description: Minimum extraction confidence before review is required
      defaultValue: 0.85
```

<Note>
  The nested `options.options` shape is intentional in the current template format.
</Note>

## Activity Plan Bindings

Activity Plans are reusable process definitions. When your environment supports binding Activity Plans in templates, treat those bindings as project setup: they should connect the reusable plan to this project's stores, data definitions, task templates, forms, Service Bridges, and statuses.

Keep the Activity Plan itself as the source of truth for steps, dependencies, script actions, Service Bridge calls, LLM steps, approvals, and Task creation.

## Validation Checklist

1. Validate the YAML syntax.
2. Create a test project from the template.
3. Confirm stores, statuses, Data Definitions, Task Templates, Data Forms, and workspace panels are created.
4. Confirm the relevant Activity Plan can run against the project resources.
5. Upload representative documents and run the workflow end to end.
6. Verify that Tasks, Activity step logs, document statuses, and audit history are visible to operators.

## Related Guides

<CardGroup cols={2}>
  <Card title="Project Templates Concept" icon="copy" href="/concepts/project_templates">
    Understand what belongs in a project template.
  </Card>

  <Card title="Activity Plans" icon="diagram-project" href="/guides/activity-plans/index">
    Model the automated work that runs inside the project.
  </Card>
</CardGroup>