# checklist

Create Checklist artifacts for task lists and verification

Canonical URL: https://docs.paradoc.dev/sdk/artifacts/checklist/

Create Checklist artifacts for tracking tasks, requirements, or verification items. Each item can have a boolean (done/not done) or enumerated status type.

## Examples

### Creating a checklist

```ts
// Object pattern
const checklist = p.checklist({
  name: 'move-in-checklist',
  version: '1.0.0',
  title: 'Move-In Inspection',
  items: [
    { id: 'keys', title: 'Keys received', status: { kind: 'boolean', default: false } },
    { id: 'condition', title: 'Property condition', status: {
      kind: 'enum',
      options: [
        { value: 'excellent', label: 'Excellent' },
        { value: 'good', label: 'Good' },
        { value: 'fair', label: 'Fair' },
        { value: 'poor', label: 'Poor' }
      ]
    }}
  ]
})

// Builder pattern
const checklist = p.checklist()
  .name('move-in-checklist')
  .version('1.0.0')
  .title('Move-In Inspection')
  .itemWithBooleanStatus('keys', 'Keys received', { default: false })
  .itemWithEnumStatus('condition', 'Property condition', {
    statusOptions: [
      { value: 'excellent', label: 'Excellent' },
      { value: 'good', label: 'Good' },
      { value: 'fair', label: 'Fair' },
      { value: 'poor', label: 'Poor' }
    ]
  })
  .build()
```

### Loading from external data

```ts
// Parse and validate unknown input (throws on error)
const checklist = p.checklist.from(jsonData)

// Safe parsing (returns result object)
const result = p.checklist.safeFrom(jsonData)
if (result.success) {
  const checklist = result.data
}
```

## API

### Object Pattern

```ts
p.checklist(input: ChecklistInput, options?: ArtifactInstanceOptions): ChecklistInstance
```

`options.resolver` reads the bytes of any file-backed layer this checklist
declares. It's bound once here, at construction, and every instance derived
from the checklist — every `fill`, mutator, and `clone` — carries it;
`render()` itself takes no resolver. See
[ArtifactInstanceOptions](/sdk/resolvers#artifactinstanceoptions).

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Unique identifier; must follow slug constraints |
| `version?` | `string` | Artifact version (semantic versioning) |
| `title?` | `string` | Human-friendly name presented to end users |
| `description?` | `string` | Long-form description or context |
| `code?` | `string` | The form number as printed by its issuer (e.g. W-9, ACORD 25), or a self-issued form's own number |
| `language?` | `string` | BCP 47 source language tag; defaults to en when omitted |
| `issuer?` | `string` | Organization that issues the form |
| `edition?` | `ArtifactEdition` | Issuer edition: { key, label, date?, effectiveFrom? } |
| `metadata?` | `Metadata` | Custom metadata map (keys must be alphanumeric with hyphens) |
| `instructions?` | `ContentRef` | Domain or compliance reference content |
| `agentInstructions?` | `ContentRef` | LLM/agent prompts for presentation guidance |
| `items` | `ChecklistItem[]` | Ordered list of checklist items to track |
| `layers?` | `Record<string, Layer>` | Named layers for rendering into different formats |
| `defaultLayer?` | `string` | Key of the default layer to use when none specified |

#### Returns

Returns a `ChecklistInstance` with the following properties and methods:

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `'checklist'` | Artifact discriminator |
| `name` | `string` | Checklist name |
| `version` | `string \| undefined` | Semantic version |
| `title` | `string \| undefined` | Human-readable title |
| `description` | `string \| undefined` | Description text |
| `code` | `string \| undefined` | The form number as printed by its issuer (e.g. W-9, ACORD 25), or a self-issued form's own number |
| `language` | `string \| undefined` | BCP 47 source language tag |
| `issuer` | `string \| undefined` | Issuing organization |
| `edition` | `ArtifactEdition \| undefined` | Issuer edition |
| `metadata` | `Metadata \| undefined` | Custom metadata map |
| `instructions` | `ContentRef \| undefined` | Domain or compliance reference content |
| `agentInstructions` | `ContentRef \| undefined` | LLM/agent prompts for presentation guidance |
| `items` | `ChecklistItem[]` | Ordered list of checklist items |
| `layers` | `Record<string, Layer> \| undefined` | Render layers |
| `defaultLayer` | `string \| undefined` | Default layer key |

**Methods**

| Name | Type | Description |
| --- | --- | --- |
| `validate` | `(options?: ValidateOptions) => StandardSchemaV1.Result` | Validate the checklist definition |
| `isValid` | `(options?: ValidateOptions) => boolean` | Check if checklist is valid |
| `toJSON` | `(options?: SerializationOptions) => object` | Serialize to JSON (includes the current dated $schema by default) |
| `toYAML` | `(options?: SerializationOptions) => string` | Serialize to YAML (includes the current dated $schema by default) |
| `clone` | `() => ChecklistInstance` | Deep clone the instance |
| `validateItemInput` | `(input: { itemId: string; value: unknown }) => ProgressiveValidationResult<boolean \| string>` | Validate one checklist item input |
| `validateItemsPatch` | `(items: unknown) => ProgressiveValidationResult<Record<string, boolean \| string>>` | Validate a partial checklist items patch |
| `fill` | `(seed?: ProgressiveChecklistPayload, options?: ChecklistFillOptions) => DraftChecklist` | Create a progressive draft; supplied values validate immediately and defaults are applied |
| `safeFill` | `(seed?: ProgressiveChecklistPayload, options?: ChecklistFillOptions) => SafeChecklistFillResult` | Safely create a progressive draft; success means the supplied patch was accepted |
| `render` | `(options?: RuntimeChecklistRenderOptions) => Promise<Output>` | Render checklist content. See [Render options](#render-options) |

### Builder Pattern

Chain methods to build a checklist incrementally:

Start with `p.checklist()`. Each method returns `ChecklistBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `name(value: string)` | Set checklist name (required) |
| `version(value: string)` | Set semantic version |
| `title(value: string)` | Set human-readable title |
| `description(value: string)` | Set description |
| `code(value: string)` | Set external reference code |
| `language(value: string)` | Set source language (BCP 47 tag) |
| `issuer(value: string)` | Set the issuing organization |
| `edition({ key, label, date?, effectiveFrom? })` | Set the issuer edition |
| `metadata(value: Metadata)` | Set custom metadata |
| `instructions(value: ContentRef)` | Set domain/compliance reference content |
| `agentInstructions(value: ContentRef)` | Set LLM/agent presentation guidance |
| `item(itemDef: ChecklistItem)` | Add a single item |
| `items(items: ChecklistItem[])` | Set all items at once |
| `itemWithBooleanStatus(id: string, title: string, options?)` | Add item with boolean status |
| `itemWithEnumStatus(id: string, title: string, options)` | Add item with enum status |
| `layers(value: Record<string, Layer>)` | Set all layers at once |
| `layer(key: string, layer: Layer)` | Add a layer from a Layer object |
| `inlineLayer(key: string, layer: { mimeType, text, ... })` | Add inline text layer |
| `fileLayer(key: string, layer: { mimeType, path, ... })` | Add file-backed layer |
| `defaultLayer(key: string)` | Set default layer for rendering |

Terminal methods return `ChecklistInstance`.

| Method | Description |
| --- | --- |
| `build(options?: ArtifactInstanceOptions)` | Build and validate; bind a resolver for file-backed layers |

### Static Methods

Parse checklists from unknown data sources. Both accept an
[`ArtifactInstanceOptions`](/sdk/resolvers#artifactinstanceoptions) to bind a
resolver for any file-backed layer:

| Method | Returns | Description |
| --- | --- | --- |
| `from(input: unknown, options?: ArtifactInstanceOptions)` | `ChecklistInstance` | Parse unknown input (throws on error) |
| `safeFrom(input: unknown, options?: ArtifactInstanceOptions)` | `Result<ChecklistInstance>` | Parse unknown input (returns result object) |

## Progressive Item Validation

Use progressive validators when collecting checklist answers interactively (for example in chat flows).

### Return shape

```ts
type ProgressiveValidationResult<T> =
  | { success: true; value: T; errors: null }
  | { success: false; value: null; errors: ValidationError[] }
```

### Validate a single item answer

```ts
const status = checklist.validateItemInput({
  itemId: 'condition',
  value: 'good',
})
```

### Validate a partial patch

```ts
const patch = checklist.validateItemsPatch({
  keys: true,
  condition: 'excellent',
})
```

Unknown item IDs and invalid enum/boolean values return structured `ValidationError[]`.

## Checklist Item Types

### ChecklistItem

Each item in a checklist has the following properties:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique item identifier within the checklist |
| `title` | `string` | Title or label displayed for this item |
| `description?` | `string` | Additional detail about the item |
| `status?` | `StatusSpec` | Status specification (boolean or enum) |

### Status Types

Checklist items can have either boolean or enumerated status tracking:

#### BooleanStatusSpec

Simple done/not-done tracking:

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `'boolean'` | Discriminator for boolean status type |
| `default?` | `boolean` | Default status value |

#### EnumStatusSpec

Multiple status states (e.g., excellent/good/fair/poor):

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `'enum'` | Discriminator for enum status type |
| `options` | `EnumStatusOption[]` | Available status options |
| `default?` | `string` | Default status value |

#### EnumStatusOption

Each option in an enum status:

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | The status value |
| `label` | `string` | Human-readable label for the status |
| `description?` | `string` | Additional description of this status |

## Lifecycle Types

Checklists follow a two-phase lifecycle:

| Type                 | Phase     | Description                           |
| -------------------- | --------- | ------------------------------------- |
| `DraftChecklist`     | Draft     | Mutable item status, can update items |
| `CompletedChecklist` | Completed | Frozen checklist, ready for archival  |

```ts
// Start with a progressive draft. Defaults are applied on creation.
const draft = checklist.fill({ keys: false })

// Incrementally answer the remaining item.
const updated = draft.update({ condition: 'good' })

// Fill accepts progressive data; completion requires every declared item after defaults.
const completeDraft = checklist.fill({ keys: true, condition: 'good' })

// Clear and restore one answer through its qualified path.
const reset = completeDraft.clear('items.keys').reset('items.keys')

// Complete the checklist (CompletedChecklist)
const completed = reset.complete()

// completed.completedAt === ISO timestamp
// Render
const output = await completed.render({ renderer: createLayerRenderer() })
```

### DraftChecklist

Created by `checklist.fill()`. Progressive drafts may be incomplete; `complete()` requires every declared item. An explicit `false` answer counts as present. Use `clear('items.<id>')` to remove an answer and `reset('items.<id>')` to restore its declared default.

| Name | Type | Description |
| --- | --- | --- |
| `phase` | `'draft'` | Phase discriminator |
| `checklist` | `Checklist` | The underlying checklist definition |
| `targetLayer` | `string` | Target layer key |
| `completedAt` | `undefined` | Completion timestamp (always undefined for draft) |

**Methods**

| Name | Type | Description |
| --- | --- | --- |
| `getItem` | `(itemId: string) => boolean \| string \| undefined` | Get status for an item |
| `getAllItems` | `() => ProgressiveChecklistPayload` | Get answered item statuses |
| `validate` | `() => ChecklistValidationResult` | Check answer validity and completeness |
| `isValid` | `() => boolean` | Check full checklist validity |
| `setItem` | `(itemId: string, value: boolean \| string) => DraftChecklist` | Set item status (returns new instance) |
| `update` | `(patch: ProgressiveChecklistPayload) => DraftChecklist` | Merge an incremental item patch |
| `safeUpdate` | `(patch: ProgressiveChecklistPayload) => { success: true; data: DraftChecklist } \| { success: false; error: Error }` | Safely merge an incremental item patch |
| `clear` | `(path: ChecklistPath) => DraftChecklist` | Remove an answer such as items.keys |
| `reset` | `(path: ChecklistPath) => DraftChecklist` | Restore an item default or remove it |
| `getFillState` | `() => ChecklistFillState` | Report unanswered and completed item slots |
| `getNextFillTarget` | `() => ChecklistFillTarget \| null` | Get the next unanswered item |
| `getAvailableFillTargets` | `() => ChecklistFillTarget[]` | Get unanswered items in declaration order |
| `setTargetLayer` | `(layer: string) => DraftChecklist` | Change target layer |
| `complete` | `() => CompletedChecklist` | Transition to completed phase |
| `render` | `(options?: RuntimeChecklistRenderOptions) => Promise<Output>` | Render the checklist |
| `toJSON` | `() => RuntimeChecklistJSON` | Serialize to JSON |
| `toYAML` | `() => string` | Serialize to YAML |
| `clone` | `() => DraftChecklist` | Create exact copy |

### CompletedChecklist

Created by `draft.complete()`. Fully frozen.

| Name | Type | Description |
| --- | --- | --- |
| `phase` | `'completed'` | Phase discriminator |
| `checklist` | `Checklist` | The underlying checklist definition |
| `targetLayer` | `string` | Target layer key |
| `completedAt` | `string` | ISO timestamp of completion |

**Methods**

| Name | Type | Description |
| --- | --- | --- |
| `getItem` | `(itemId: string) => boolean \| string` | Get status for an item |
| `getAllItems` | `() => Record<string, boolean \| string>` | Get all item statuses |
| `validate` | `() => ChecklistValidationResult` | Validate the completed checklist |
| `isValid` | `() => boolean` | Check completed checklist validity |
| `render` | `(options?: RuntimeChecklistRenderOptions) => Promise<Output>` | Render the checklist |
| `toJSON` | `() => RuntimeChecklistJSON` | Serialize to JSON |
| `toYAML` | `() => string` | Serialize to YAML |
| `clone` | `() => CompletedChecklist` | Create exact copy |

## Render options

`render()` takes `RuntimeChecklistRenderOptions`. It picks a renderer the way a form does: `renderer`, then the entry in `renderers` for the layer's MIME type, then the built-in engine for that type, which evaluates `{{items.x}}`.

| Name | Type | Description |
| --- | --- | --- |
| `layer?` | `string` | Layer key to render. Defaults to the target layer |
| `renderer?` | `ParadocRenderer` | Renderer that processes the layer template, such as `createLayerRenderer()` |
| `renderers?` | `RendererRegistry` | Renderers keyed by layer MIME type, consulted after `renderer` and before the built-in engine |
| `formatter?` | `Formatter` | Formatter used for values in this render |
| `progressive?` | `FormatterProgressivePolicy` | Text for missing and incomplete values |

## Related

* [Checklist Schema](/schemas/artifacts/checklist)
* [Renderers](/sdk/renderers)
* [Formatting](/sdk/formatting)