> ## Documentation Index > Fetch the complete documentation index at: https://docs.fabriqa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Artifact schemas > Define artifact structure, lifecycles, and document semantics. # Artifact schemas Artifact schema files are the center of the Workflow DSL. They define: * the artifact type * its parent requirement * its lifecycle * its payload shape * its document semantics ## Full example This example is intentionally planning-oriented so it demonstrates document sections while relying on Fabriqa's automatic metadata for targeting, tags, and status. ```yaml theme={null} artifact: id: work_item name: Work Item icon: list-todo phase: plan parent: intent lifecycle: initial: draft states: - id: draft label: Draft actor: system - id: in_review label: In review actor: human handoff: true - id: approved label: Approved actor: human - id: superseded label: Superseded actor: system terminal: true schema: type: object properties: summary: type: string required: true description: Markdown summary of the work item and the intended user-visible outcome. problem_statement: type: string required: false description: Markdown description of the problem being solved and why it matters. delivery_notes: type: string required: false description: Markdown notes describing scope boundaries, constraints, and implementation direction. acceptance_criteria: type: array required: false items: type: string description: Concrete acceptance criteria used to judge whether the work item is complete. document: sections: - id: summary title: Summary field: summary kind: markdown - id: problem title: Problem statement field: problem_statement kind: markdown - id: delivery title: Delivery notes field: delivery_notes kind: markdown - id: acceptance title: Acceptance criteria field: acceptance_criteria kind: markdown ``` Fabriqa still adds built-in metadata such as `status`, `tags`, `target_scope`, and `target_workspace_project_ids` to this artifact type. Workflow authors do not repeat those fields in the schema unless Fabriqa later makes one of them workflow-authored. ## `artifact` The `artifact` block defines the artifact's identity. ```yaml theme={null} artifact: id: walkthrough name: Walkthrough icon: file-text phase: build ``` Rules: * `id`, `name`, and `phase` are required. * `phase` must reference a phase from `workflow.yaml`. * `id` must match the key used in `workflow.yaml -> artifacts`. ## `parent` `parent` declares the required parent artifact type. ```yaml theme={null} parent: run ``` Rules: * Omit `parent` for root artifacts. * When present, Fabriqa derives child relationships automatically. * Agents should create the artifact under a real parent instance of that type. ## `lifecycle` Define lifecycle state directly in the artifact schema. ```yaml theme={null} lifecycle: initial: draft states: - id: draft label: Draft actor: system - id: verified label: Verified actor: human handoff: true ``` For now, Fabriqa keeps lifecycles inline for simplicity. Inline lifecycles are anonymous in V1. You do not give them a separate `id` or `name` because: * the lifecycle only belongs to this artifact file * Fabriqa does not reference inline lifecycles independently * repeating lifecycle labels adds verbosity without adding runtime value This keeps artifact meaning local: * one artifact file contains its own state machine * authors do not need to jump between schema files to understand lifecycle state * built-in workflows intentionally repeat lifecycle blocks when several artifact types share the same states ## `schema` `schema` is a Fabriqa-authored schema block that compiles to canonical JSON Schema internally. It is the source of truth for: * field names * types * enums * required fields * nested structures * field descriptions * field-local requiredness Recommended rules: * use `type: object` at the root * Fabriqa treats artifact payload objects as closed by default in V1, so define every supported field explicitly * agents may only create or update fields that are declared in `schema.properties` plus built-in system fields such as `tags`, `target_scope`, `target_workspace_project_ids`, and `touched_workspace_project_ids` * declare requiredness on the field itself with `required: true` or `required: false` * use `description` aggressively * keep field names stable Example: ```yaml theme={null} schema: type: object properties: summary: type: string required: true description: Markdown summary of the artifact. ``` ## `document` `document` defines the semantic document structure for the artifact detail view. ```yaml theme={null} document: sections: - id: summary title: Summary field: summary kind: markdown ``` Use `document` to say: * which fields form the main document body * the order of the main reader experience Fabriqa automatically treats every schema-defined field not claimed by a document section, plus built-in system fields, as artifact metadata. Artifact schemas do not define a per-artifact `ui` block in V1. Fabriqa already knows how to render: * markdown string fields * enums and primitive values * string arrays such as tags, project IDs, and touched files * system fields such as `status`, `created_at`, and `updated_at` Workflow-level shell surfaces such as sidebar defaults still belong in `workflow.yaml -> ui`. Dashboard and root artifact viewer behavior are product-defined in V1. ### `document.sections` Use `document.sections` for the main document body. Preferred pattern: ```yaml theme={null} sections: - id: summary title: Summary field: summary kind: markdown ``` Rules: * Prefer `field` for almost every section. * `field` should usually point to a string property rendered as markdown. * Use `kind: markdown` for both string fields and `array` fields. Arrays of strings should render as bullet lists in the document body. * If one markdown section uses multiple `fields`, Fabriqa combines those values into one markdown block in reading order instead of rendering them as separate widgets. * Use `fields` only when you need one structured section to display several primitive or list fields together. Supported section keys: | Key | Required | Purpose | | -------- | ----------- | ------------------------------------------------ | | `id` | Yes | Stable identifier | | `title` | Yes | Section heading in the document view | | `field` | Recommended | The primary field for markdown-like sections | | `fields` | Optional | Escape hatch for structured multi-field sections | | `kind` | Optional | Viewer hint such as `markdown` or `structured` | ## System fields Fabriqa injects system fields into every artifact even though you do not declare them in `schema`. | Field | Meaning | | ------------------------------- | -------------------------------------------------------------------------- | | `title` | Artifact title | | `description` | Artifact summary description | | `status` | Current lifecycle status | | `priority` | Optional artifact priority | | `phase` | Current workflow phase | | `assignee` | Claimed agent or assignee | | `tags` | Freeform string tags any agent can attach to the artifact | | `target_scope` | Built-in planning target scope such as `workspace` or `workspace_project` | | `target_workspace_project_ids` | Built-in planning target project IDs when the artifact is project-targeted | | `touched_workspace_project_ids` | Built-in execution tracking for projects actually changed | | `created_at` | Creation timestamp | | `updated_at` | Last update timestamp | | `completed_at` | Completion timestamp | | `display_id` | Human-friendly display identifier | Do not duplicate them in `schema`. `tags` is the default cross-workflow tagging mechanism. * every artifact has `tags` as a system-managed string array * agents can add or update tags when they decide they are useful * workflows can surface tags automatically in artifact metadata, sidebar views, dashboard filters, and later UI features * tags are metadata, not part of the main document body ## Automatic metadata Fabriqa infers artifact metadata automatically. The rule is simple: * if a field is used by `document.sections`, it is part of the document body * every other schema-defined field becomes metadata automatically * built-in system fields such as `status`, `tags`, `target_scope`, `target_workspace_project_ids`, `touched_workspace_project_ids`, and timestamps also appear as metadata automatically Keep metadata small and readable. If something wants to be read like prose, it usually belongs in a section instead. ## How artifact documents render Fabriqa renders artifact documents with one simple rule: the body should read like a markdown document, not like a form. That means: * markdown sections render with Fabriqa's read-only markdown renderer * markdown string arrays render as bullet lists * non-section primitive fields and small arrays render as compact metadata under the title * child artifacts do not render again in the document body because the hierarchy already appears in the artifact viewer tree * relations, linked chats, and activity belong in the contextual rail, not the document body Good document behavior: * one clear title * a small metadata row under the title * markdown sections in natural reading order * minimal chrome and restrained separators Bad document behavior: * checklist widgets for narrative requirements * repeating child artifacts inside both the tree and the body * turning relations or chat links into main document content * heavy card stacks that make the artifact feel like an admin panel ## Document-first authoring guidance Fabriqa renders artifacts best when you separate document content from operational metadata. | Put it in `document.sections` | Leave it as automatic metadata | | ----------------------------- | ------------------------------ | | summaries | status | | rationale | priority | | architecture notes | phase | | implementation notes | current stage | | verification narratives | timestamps | | rollout notes | target scope | Good pattern: * `summary` as markdown * `implementation_notes` as markdown * `verification_summary` as markdown * `verification_verdict` left as metadata * `touched_workspace_project_ids` left as metadata Weaker pattern: * large arrays of nested objects used as the main body of a design document * artifact viewers that feel like forms instead of documents ## Scope and associations Fabriqa workflows often need explicit project targeting and structural associations. ### Planning scope Fabriqa provides built-in planning target fields. Workflow authors should not redefine them in `schema.properties`. Rules: * use `target_scope: workspace` when the artifact applies to the whole workspace * use `target_scope: workspace_project` when the artifact targets one or more specific workspace projects * require `target_workspace_project_ids` only when `target_scope` is `workspace_project` * do not store project names as canonical artifact data; resolve names from workspace metadata using the IDs Keep workspace-wide targeting as a first-class concept. Why: * some planning artifacts intentionally span the whole workspace before decomposition narrows to individual projects * cross-project migrations, shared platform work, release coordination, and standards or policy artifacts do not naturally belong to one project * third-party workflows may operate above single-project scope as well Typical pattern: * `intent` may be workspace-scoped for multi-project planning * `unit`, `story`, `work_item`, and `bolt` often become `workspace_project` scoped as planning gets more concrete ### Execution tracking Fabriqa also provides `touched_workspace_project_ids` as a built-in field when agents want to record what was actually changed during execution. ### Parent associations Use `parent` for structural ownership such as: * `work_item` under `intent` * `walkthrough` under `run` * `test_report` under `bolt` The agent prompt should still instruct the agent to create the artifact under the correct parent. The DSL makes that requirement explicit and machine-readable. ## Continue reading Go back to the workflow envelope and orchestration rules. Continue into SAF files, prompts, templates, and authoring rules. See these artifact-schema patterns applied to the built-in AI-DLC workflow. Review the shared vocabulary for document semantics and lifecycles.