checklistLast updated on
Last updated on
Create Checklist artifacts for task lists and verification
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 = open.checklist({
name: 'move-in-checklist',
version: '1.0.0',
title: 'Move-In Inspection',
items: [
{ id: 'keys', title: 'Keys received', status: { kind: 'boolean' } },
{ 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 = open.checklist()
.name('move-in-checklist')
.version('1.0.0')
.title('Move-In Inspection')
.itemWithBooleanStatus('keys', 'Keys received')
.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 = open.checklist.from(jsonData)
// Safe parsing (returns result object)
const result = open.checklist.safeFrom(jsonData)
if (result.success) {
const checklist = result.data
}API
Object Pattern
open.checklist(input: ChecklistInput): ChecklistInstanceParameters
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
Internal code or reference number
releaseDate?: string
ISO date string indicating when the artifact was released
metadata?: Metadata
Custom metadata map (keys must be alphanumeric with hyphens)
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
name: string
Checklist name
version: string | undefined
Semantic version
title: string | undefined
Human-readable title
description: string | undefined
Description text
code: string | undefined
Internal code or reference number
releaseDate: string | undefined
ISO date string
metadata: Metadata | undefined
Custom metadata map
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 $schema by default)
toYAML: (options?: SerializationOptions) => string
Serialize to YAML
clone: () => ChecklistInstance
Deep clone the instance
fill: (data: InferChecklistPayload) => DraftChecklist
Create runtime checklist with item status data
safeFill: (data: InferChecklistPayload) => Result<DraftChecklist>
Safely fill with error handling
render: (options?: RuntimeChecklistRenderOptions) => Promise<Output>
Render checklist content
Builder Pattern
Chain methods to build a checklist incrementally:
All methods return ChecklistBuilder and are chainable.
open.checklist()
name: (value: string) => ChecklistBuilder
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
releaseDate: (value: string) => ChecklistBuilder
Set release date (ISO format)
metadata: (value: Metadata) => ChecklistBuilder
Set custom metadata
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: () => ChecklistInstance
Build and validate
Static Methods
Parse checklists from unknown data sources:
from: (input: unknown) => ChecklistInstance
Parse unknown input (throws on error)
safeFrom: (input: unknown) => Result<ChecklistInstance>
Parse unknown input (returns result object)
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 |
// Fill checklist with initial data (DraftChecklist)
const draft = checklist.fill({
keys: true,
condition: 'good',
})
// Update items
const updated = draft.setItem('keys', true)
// Complete the checklist (CompletedChecklist)
const completed = draft.complete()
// completed.completedAt === ISO timestamp
// Render
const output = await completed.render({ renderer: textRenderer() })DraftChecklist
Created by checklist.fill(). Mutable item status tracking.
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
Get status for an item
getAllItems: () => Record<string, boolean | string>
Get all item statuses
setItem: (itemId: string, value: boolean | string) => DraftChecklist
Set item status (returns new instance)
updateItems: (updates: Partial<Payload>) => DraftChecklist
Update multiple items at once
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
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
render: (options?: RuntimeChecklistRenderOptions) => Promise<Output>
Render the checklist
toJSON: () => RuntimeChecklistJSON
Serialize to JSON
clone: () => CompletedChecklist
Create exact copy