Skip to main content

​
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. 
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. 
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. 
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. 
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: 
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. 
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: 
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<string> 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:
KeyRequiredPurpose
idYesStable identifier
titleYesSection heading in the document view
fieldRecommendedThe primary field for markdown-like sections
fieldsOptionalEscape hatch for structured multi-field sections
kindOptionalViewer hint such as markdown or structured

​
System fields

Fabriqa injects system fields into every artifact even though you do not declare them in schema.
FieldMeaning
titleArtifact title
descriptionArtifact summary description
statusCurrent lifecycle status
priorityOptional artifact priority
phaseCurrent workflow phase
assigneeClaimed agent or assignee
tagsFreeform string tags any agent can attach to the artifact
target_scopeBuilt-in planning target scope such as workspace or workspace_project
target_workspace_project_idsBuilt-in planning target project IDs when the artifact is project-targeted
touched_workspace_project_idsBuilt-in execution tracking for projects actually changed
created_atCreation timestamp
updated_atLast update timestamp
completed_atCompletion timestamp
display_idHuman-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.sectionsLeave it as automatic metadata
summariesstatus
rationalepriority
architecture notesphase
implementation notescurrent stage
verification narrativestimestamps
rollout notestarget 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

Workflow file

Go back to the workflow envelope and orchestration rules.

Agents and connectors

Continue into SAF files, prompts, templates, and authoring rules.

AI-DLC definition

See these artifact-schema patterns applied to the built-in AI-DLC workflow.

Workflow glossary

Review the shared vocabulary for document semantics and lifecycles.