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

// 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

// 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

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.

Parameters

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:

kind: 'checklist'

Artifact discriminator

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

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:

All methods return ChecklistBuilder and are chainable.

p.checklist()

Set checklist name (required)

version: (value: string) => ChecklistBuilder

Set semantic version

title: (value: string) => ChecklistBuilder

Set human-readable title

description: (value: string) => ChecklistBuilder

Set description

code: (value: string) => ChecklistBuilder

Set external reference code

language: (value: string) => ChecklistBuilder

Set source language (BCP 47 tag)

issuer: (value: string) => ChecklistBuilder

Set the issuing organization

edition: ({ key, label, date?, effectiveFrom? }) => ChecklistBuilder

Set the issuer edition

metadata: (value: Metadata) => ChecklistBuilder

Set custom metadata

instructions: (value: ContentRef) => ChecklistBuilder

Set domain/compliance reference content

agentInstructions: (value: ContentRef) => ChecklistBuilder

Set LLM/agent presentation guidance

item: (itemDef: ChecklistItem) => ChecklistBuilder

Add a single item

items: (items: ChecklistItem[]) => ChecklistBuilder

Set all items at once

itemWithBooleanStatus: (id: string, title: string, options?) => ChecklistBuilder

Add item with boolean status

itemWithEnumStatus: (id: string, title: string, options) => ChecklistBuilder

Add item with enum status

layers: (value: Record<string, Layer>) => ChecklistBuilder

Set all layers at once

layer: (key: string, layer: Layer) => ChecklistBuilder

Add a layer from a Layer object

inlineLayer: (key: string, layer: { mimeType, text, ... }) => ChecklistBuilder

Add inline text layer

fileLayer: (key: string, layer: { mimeType, path, ... }) => ChecklistBuilder

Add file-backed layer

defaultLayer: (key: string) => ChecklistBuilder

Set default layer for rendering

build: (options?: ArtifactInstanceOptions) => ChecklistInstance

Build and validate; bind a resolver for file-backed layers

Static Methods

Parse checklists from unknown data sources. Both accept an ArtifactInstanceOptions to bind a resolver for any file-backed layer:

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

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

Validate a single item answer

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

Validate a partial patch

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:

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:

kind: 'boolean'

Discriminator for boolean status type

default?: boolean

Default status value

EnumStatusSpec

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

kind: 'enum'

Discriminator for enum status type

options: EnumStatusOption[]

Available status options

default?: string

Default status value

EnumStatusOption

Each option in an enum status:

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

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

phase: 'draft'

Phase discriminator

checklist: Checklist

The underlying checklist definition

targetLayer: string

Target layer key

completedAt: undefined

Completion timestamp (always undefined for draft)

Methods

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.

phase: 'completed'

Phase discriminator

checklist: Checklist

The underlying checklist definition

targetLayer: string

Target layer key

completedAt: string

ISO timestamp of completion

Methods

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

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

checklist
Last updated on

Examples

Creating a checklist

Loading from external data

API

Object Pattern

Parameters

Returns

Builder Pattern

Static Methods

Progressive Item Validation

Return shape

Validate a single item answer

Validate a partial patch

Checklist Item Types

ChecklistItem

Status Types

BooleanStatusSpec

EnumStatusSpec

EnumStatusOption

Lifecycle Types

DraftChecklist

CompletedChecklist

Render options

On this page

checklistLast updated on

On this page

checklist
Last updated on