Specification

LagomDocument specification

The complete schema reference for Lagom documents. Covers the root document object, sections, typed elements, variables, governance metadata, and file format conventions.

Root object

LagomDocument

Every Lagom document resolves to a LagomDocument object. Whether authored as .lagom.md or .lagom.json, the parsed result conforms to this interface. The document carries metadata, content sections, variables, entity references, connector bindings, agent actions, and governance rules.

LagomDocument interface

interface LagomDocument {
  $schema: string;              // Schema URL for validation
  lagomVersion: string;         // Spec version (e.g. "1.0")
  kind: "LagomDocument";        // Discriminator
  id: string;                   // Stable unique identifier
  title: string;                // Document title
  description?: string;         // Optional summary
  documentType: DocumentType;   // sop | policy | playbook | ...
  status: DocumentStatus;       // draft | active | deprecated | archived
  owner?: OwnerRef;             // Owner team or person
  aliases?: string[];           // Alternative names for resolution
  sections: LagomSection[];     // Ordered content sections
  variables?: LagomVariable[];  // Document-scoped variables
  entities?: BusinessEntityRef[];  // Referenced business entities
  connectors?: ConnectorRef[];  // External system connectors
  actions?: AgentAction[];      // Declared agent actions
  governance?: GovernanceMetadata;  // Ownership and review rules
  references?: DocumentReference[];  // Typed relationships
  extensions?: Record<string, unknown>;  // Namespaced custom data
}

Field	Type	Required	Description
`$schema`	`string`	yes	URL to the Lagom JSON Schema for validation
`lagomVersion`	`string`	yes	Spec version this document conforms to
`kind`	`"LagomDocument"`	yes	Type discriminator, always "LagomDocument"
`id`	`string`	yes	Stable unique identifier for cross-referencing
`title`	`string`	yes	Document title for display, search, and agent context
`documentType`	`DocumentType`	yes	One of: sop, policy, playbook, decision, guide, workflow
`status`	`DocumentStatus`	yes	Lifecycle state: draft, active, deprecated, archived
`sections`	`LagomSection[]`	yes	Ordered list of content sections
`owner`	`OwnerRef`	no	Team or person responsible for this document
`governance`	`GovernanceMetadata`	no	Review cadence, confidence, staleness rules

Sections

LagomSection

Sections are the top-level organizational unit within a document. Each section has a stable ID, a title, and an ordered list of typed elements. In .lagom.md, sections correspond to Markdown headings.

LagomSection interface

interface LagomSection {
  id: string;                   // Stable section identifier
  title: string;                // Section heading
  elements: LagomElement[];     // Ordered typed blocks
  visibility?: VisibilityScope; // internal | external | public | private
}

Element types

LagomElement union

Every block in a Lagom document is a typed element. The element type is a discriminated union on the type field. Each element has an id, optional label, and type-specific properties. Unknown types are rejected unless namespaced under extensions.

LagomElement union

type LagomElement =
  | MarkdownBlock         // Prose, headings, lists, links
  | StepBlock             // SOP step with owner, tool, inputs
  | ChecklistBlock        // Ordered task checklist
  | DecisionBlock         // Recorded decision with rationale
  | PolicyRuleBlock       // Policy rule with scope and exceptions
  | PromptBlock           // Reusable AI prompt template
  | AgentActionBlock      // Declared tool action for AI agents
  | DataReferenceBlock    // Reference to external data source
  | ApprovalBlock         // Human approval gate
  | SystemReferenceBlock  // External system dependency
  | EvidenceBlock         // Source, citation, provenance
  | MermaidBlock          // Diagram (Mermaid syntax)
  | TableBlock;           // Structured data table

All element types

Markdown

Step

Checklist

Decision

PolicyRule

Prompt

AgentAction

DataReference

Approval

SystemReference

Evidence

Mermaid

Table

StepBlock

Represents a single procedure step in an SOP or workflow. Steps carry ownership, tooling, input/output contracts, and approval requirements.

StepBlock

interface StepBlock {
  type: "step";
  id: string;
  title: string;
  description?: string;
  owner?: string;              // Role or person
  system?: string;             // System of record
  tool?: string;               // Tool identifier (e.g. google_drive.create_folder)
  requiresApproval?: boolean;  // Gate before execution
  inputMap?: Record<string, string>;  // Variable bindings
  requiredEntity?: string;     // Business entity dependency
  expectedDuration?: string;   // Human-readable estimate
}

AgentActionBlock

Declares a safe, reviewable action that an AI agent can perform. Agent actions are declarative and mediated by runtime policy. They never allow arbitrary code execution.

AgentActionBlock

interface AgentActionBlock {
  type: "agent_action";
  id: string;
  tool: string;               // MCP server/tool identifier
  description?: string;
  requiresApproval: boolean;  // Always explicit
  inputMap?: Record<string, string>;  // Variable bindings
  permissions?: string[];     // Required permissions
  dryRun?: boolean;           // Preview-only mode
}

PolicyRuleBlock

Captures a business policy rule with scope, severity, exceptions, and enforcement context. Policy rules export as structured constraints for AI agents.

PolicyRuleBlock

interface PolicyRuleBlock {
  type: "policy_rule";
  id: string;
  rule: string;               // The policy statement
  appliesTo: string;          // Scope (e.g. all-employees)
  severity: "standard" | "critical";
  exceptions?: string[];      // Listed exceptions
  owner?: string;
  effectiveDate?: string;
  reviewCadence?: string;
}

Governance

GovernanceMetadata

Governance metadata tracks ownership, review cadence, freshness, confidence, and agent readiness. This data powers dashboards, stale-document detection, and agent context filtering.

GovernanceMetadata

interface GovernanceMetadata {
  owner?: string;              // Responsible team or person
  reviewer?: string;           // Designated reviewer
  department?: string;         // Organizational unit
  reviewCadence?: string;      // monthly | quarterly | annually
  lastVerifiedAt?: string;     // ISO 8601 date
  staleAfterDays?: number;     // Days before flagged stale
  confidence?: "low" | "medium" | "high";
  riskLevel?: "low" | "medium" | "high";
  agentReady?: boolean;        // Safe for agent consumption
  externalSharingAllowed?: boolean;
  sourceOfTruth?: boolean;     // Canonical source document
}

File formats

Authoring conventions

Lagom documents can be authored in two formats. Both parse to the same LagomDocument object and round-trip without loss.

Extension	Format	Use case
`.lagom.md`	Markdown + YAML fenced blocks	Human authoring, git diffs, AI agent consumption
`.lagom.json`	Canonical JSON	Applications, validation, programmatic generation

In .lagom.md, document metadata lives in YAML frontmatter. Typed blocks use fenced code blocks with Lagom-namespaced language tags such as lagom.step, lagom.agent_action, lagom.policy_rule, lagom.checklist, lagom.decision, and lagom.approval_gate. Plain Markdown sections and prose are treated as MarkdownBlock elements.

Resources

Schema, types, and runtime assets for developers integrating the LagomDocument format. All assets are served from this origin. Pin $schema to the schema URL below.

Path	Description
`/schema/v1/idoc_v1.json`	JSON Schema for document validation
`/schema/v1/idoc_v1.d.ts`	TypeScript type definitions
`/dist/v1/chartifact.markdown.umd.js`	Markdown rendering runtime
`/dist/v1/chartifact.sandbox.umd.js`	Sandbox execution environment
`/dist/v1/chartifact.compiler.umd.js`	Document compiler
`/dist/v1/chartifact-reset.css`	Base stylesheet for rendered documents