documentLast updated on
Last updated on
Create Document artifacts for static content
Create Document artifacts for disclosures, pamphlets, or any static content that can be rendered to different formats via layers.
Examples
Creating a document
// Object pattern
const doc = open.document({
name: 'privacy-disclosure',
version: '1.0.0',
title: 'Privacy Disclosure',
layers: {
html: { kind: 'inline', mimeType: 'text/html', text: '<p>...</p>' }
},
defaultLayer: 'html'
})
// Builder pattern
const doc = open.document()
.name('privacy-disclosure')
.version('1.0.0')
.title('Privacy Disclosure')
.inlineLayer('html', { mimeType: 'text/html', text: '<p>...</p>' })
.defaultLayer('html')
.build()Loading from external data
// Parse and validate unknown input (throws on error)
const doc = open.document.from(jsonData)
// Safe parsing (returns result object)
const result = open.document.safeFrom(jsonData)
if (result.success) {
const doc = result.data
}API
Object Pattern
open.document(input: DocumentInput): DocumentInstanceParameters
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)
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 DocumentInstance with the following properties and methods:
kind: 'document'
Artifact discriminator
name: string
Document 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
layers: Record<string, Layer> | undefined
Render layers
defaultLayer: string | undefined
Default layer key
Methods
validate: (options?: ValidateOptions) => StandardSchemaV1.Result
Validate the document definition
isValid: (options?: ValidateOptions) => boolean
Check if document is valid
toJSON: (options?: SerializationOptions) => object
Serialize to JSON (includes $schema by default)
toYAML: (options?: SerializationOptions) => string
Serialize to YAML
clone: () => DocumentInstance
Deep clone the instance
prepare: (targetLayer?: string) => DraftDocument
Create a runtime document in draft phase
render: (options?: LayerRenderOptions) => Promise<string | Uint8Array>
Render document content
Builder Pattern
Chain methods to build a document incrementally:
All methods return DocumentBuilder and are chainable.
open.document()
name: (value: string) => DocumentBuilder
Set document name (required)
version: (value: string) => DocumentBuilder
Set semantic version
title: (value: string) => DocumentBuilder
Set human-readable title
description: (value: string) => DocumentBuilder
Set description
code: (value: string) => DocumentBuilder
Set external reference code
releaseDate: (value: string) => DocumentBuilder
Set release date (ISO format)
metadata: (value: Metadata) => DocumentBuilder
Set custom metadata
layers: (value: Record<string, Layer>) => DocumentBuilder
Set all layers at once
layer: (key: string, layer: Layer) => DocumentBuilder
Add a layer from a Layer object
inlineLayer: (key: string, layer: { mimeType, text, ... }) => DocumentBuilder
Add inline text layer
fileLayer: (key: string, layer: { mimeType, path, ... }) => DocumentBuilder
Add file-backed layer
defaultLayer: (key: string) => DocumentBuilder
Set default layer for rendering
build: () => DocumentInstance
Build and validate
Static Methods
Parse documents from unknown data sources:
from: (input: unknown) => DocumentInstance
Parse unknown input (throws on error)
safeFrom: (input: unknown) => Result<DocumentInstance>
Parse unknown input (returns result object)
Lifecycle Types
Documents follow a two-phase lifecycle:
| Type | Phase | Description |
|---|---|---|
DraftDocument | Draft | Document ready for finalization |
FinalDocument | Final | Frozen document, ready for archival |
// Prepare document (DraftDocument)
const draft = doc.prepare('html')
// Finalize (FinalDocument)
const final = draft.finalize()
// final.finalizedAt === ISO timestamp
// Render
const output = await final.render({ renderer: textRenderer() })DraftDocument
Created by doc.resolve(). Contains resolved layer content.
phase: 'draft'
Phase discriminator
document: Document
The underlying document definition
resolvedContent: string | Uint8Array
Resolved layer content
targetLayer: string
Target layer key
Methods
finalize: () => FinalDocument
Transition to final phase
render: (options: RenderOptions) => Promise<Output>
Render the document
toJSON: () => DraftDocumentJSON
Serialize to JSON
FinalDocument
Created by draft.finalize(). Fully frozen.
phase: 'final'
Phase discriminator
finalizedAt: string
ISO timestamp of finalization
Methods
render: (options: RenderOptions) => Promise<Output>
Render the document
toJSON: () => FinalDocumentJSON
Serialize to JSON