Validate Templates

Validate a Template before you share it or generate Tasks from it. Validation never creates Tasks.

Two Separate Choices

Every validation run makes two independent choices. Don't confuse them: connecting to Azure DevOps doesn't make validation stricter, and strict mode doesn't connect.

Choice	Options	What it decides
Where the checks run	Offline Validation (default) or Online Validation	Whether Atomize also checks the Template's references against your Azure DevOps project
How strict it is	Lenient (default) or strict	Whether warnings fail validation

Errors always fail validation. In lenient mode, warnings are reported but the Template is still valid. In strict mode, every warning becomes an error.

Offline And Online Validation

Offline Validation checks the Template on its own: its structure and field types, task counts and estimation totals, dependencies and repetition, conditions, the estimation configuration, and its composition with any parent and Mixins. It needs no Connection Profile and finishes immediately, so every tool runs it while you author.

Online Validation runs those checks and also connects through a Connection Profile to check what only your project can confirm:

• custom field reference names, whether each is read-only, its type, and picklist values;
• fields named in conditions;
• the saved query in filter.savedQuery;
• the estimation settings: whether estimation.source, taskType, and each targetFields entry exist and can hold the value, and whether conversion.table covers the source field's allowed values.

Without a connection, those checks can't run. Offline Validation reports a warning such as 1 task(s) have custom fields that could not be verified instead, so a strict run fails until you validate online.

Online Validation needs a Connection Profile whose token has the Work Items scope. If Atomize can't connect, it reports Could not validate project references against ADO: … as a warning and finishes the offline checks. A lenient run still passes; a strict run fails. Fix the connection with connection troubleshooting and validate again.

Field assistance is not validation. Field and query browsers, field suggestions in the CLI wizard help you pick names that exist while you author. They only cover the value you're choosing. Online Validation checks every reference in the Template, including ones typed by hand or copied from another project, so run it before you share a Template or generate from it.

Run Validation In Your Tool

CLI. atomize validate validates one Template, by file path, Catalog ref, or HTTPS URL:

atomize validate my-template.atomize.yaml            # Offline Validation, lenient unless the Template sets strict
atomize validate my-template.atomize.yaml --strict   # warnings become errors
atomize validate template:backend-api --profile work-ado   # Online Validation through a profile
atomize validate my-template.atomize.yaml --output json    # a ValidationResult object, with suggested fixes

In an interactive terminal, a Template that has references only Online Validation can check asks whether to validate offline or online; --strict selects Online first. The command exits with 0 when the Template is valid and 1 when it isn't. See validate for every option.

VS Code. Saving an Atomize YAML File runs Offline Validation and updates the Problems panel without opening anything. Run Atomize: Validate to choose Offline or Online Validation and open a Validation Report that lists each error and warning with its suggested fix. See Atomize: Validate.

VS Code use the Template's own validation.mode. To validate strictly there, set mode: "strict" in the Template, or run atomize validate --strict.

To validate several Templates in a script or CI job, run atomize validate once per file:

for template in templates/*.atomize.yaml; do
  atomize validate "$template" --strict || exit 1
done

Lenient and strict

	Lenient	Strict
Errors	Block template use	Block template use
Warnings	Non-blocking, shown as info	Promoted to errors, block template use
Default	Yes	No
Use case	Development, flexible templates	Production, QA gates, CI/CD

---

Lenient Mode

Lenient is the default mode. Only hard errors block a template from being used. Warnings are displayed but do not cause the validation to fail.

Characteristics:

• Errors → template is invalid, must be fixed
• Warnings → template is valid, but may behave unexpectedly
• Great for development and iterating on templates

Example output (lenient):

Template is valid! [Lenient]

Warnings:
  • tasks[*].customFields: 1 task(s) have custom fields that could not be verified.
     Run with --profile <name> (or choose Online when prompted) to validate field names, types, and picklist values.

Ready to use with: atomize generate my-template.yaml

---

Strict Mode

In strict mode, all warnings are promoted to errors. The template is invalid if any warning exists, regardless of whether errors are present.

Characteristics:

• Errors → template is invalid
• Warnings → also treated as errors, template is invalid
• Best for production templates and automated pipelines
• Enforces high quality and catches potential issues early

Example output (strict):

Template validation failed [Strict]

Errors:
  • tasks[*].customFields: 1 task(s) have custom fields that could not be verified.
     Run with --profile <name> (or choose Online when prompted) to validate field names, types, and picklist values.

Fix the errors above and try again.

How to set the mode

Via CLI Flags (Recommended)

Override the mode at the command line for the current run:

# Use strict mode for this validation
atomize validate my-template.yaml --strict

# Connect to ADO for live custom-field and saved-query validation
atomize validate my-template.yaml --profile work-ado

Via Template YAML

Set the default mode inside the template itself. This is useful when you want to enforce a mode for a specific template regardless of how it's called.

validation:
  mode: "strict"    # or "lenient"
  totalEstimationMustBe: 100
  minTasks: 3

Precedence

CLI flags override the template's validation.mode setting:

CLI --strict  >  template validation.mode  >  lenient (default)

When Azure DevOps-backed validation is needed:

• atomize validate runs Offline Validation by default and only checks structure
• atomize validate --profile <name> performs Online Validation against Azure DevOps: custom fields, saved queries, and the estimation settings (estimation.source, taskType, targetFields, and conversion.table against the source field's allowed values)
• In interactive terminals, Atomize may prompt you to choose Offline Validation or Online Validation

---

When to Use Each Mode

Use Lenient Mode for:

• Developing new templates: iterate quickly without strict checks blocking you
• Experimental or personal templates: where flexibility matters more than rigidity
• Templates with optional tasks: where conditional tasks may cause warning-level issues
• Generating tasks interactively: the default mode is appropriate for everyday use

Use Strict Mode for:

• Shared team templates: enforce quality for templates used across the team
• CI/CD pipelines: ensure templates meet all quality gates before merging
• Production-critical templates: for templates that run automatically
• Template reviews: catch every potential issue before releasing a template

# CI/CD example: validate all templates strictly
for template in templates/*.yaml; do
  atomize validate "$template" --strict
done

---

Examples

Template That Passes Both Modes

formatVersion: "1.0"
name: "Bug Fix Workflow"
description: "Standard bug fix process"

filter:
  workItemTypes: ["Bug"]
  states: ["New", "Active"]
  excludeIfHasTasks: true

tasks:
  - id: "investigate"
    title: "Investigate & Reproduce Bug"
    estimationPercent: 30
    activity: "Testing"

  - id: "fix"
    title: "Implement Fix"
    estimationPercent: 40
    activity: "Development"
    dependsOn: ["investigate"]

  - id: "test"
    title: "Test & Verify Fix"
    estimationPercent: 20
    activity: "Testing"
    dependsOn: ["fix"]

  - id: "review"
    title: "Review & Deploy"
    estimationPercent: 10
    activity: "Documentation"
    dependsOn: ["test"]

validation:
  mode: "strict"
  totalEstimationMustBe: 100
  minTasks: 3

Template That Passes Lenient but Fails Strict

tasks:
  - title: "Implementation"
    estimationPercent: 70
    customFields:
      Custom.ReleaseVersion: "{{ story.customFields['Custom.ReleaseVersion'] }}"

  - title: "Testing"
    estimationPercent: 30

Lenient output:

Template is valid! [Lenient]
Warnings:
  • tasks[*].customFields: 1 task(s) have custom fields that could not be verified.

Strict output:

Template validation failed [Strict]
Errors:
  • tasks[*].customFields: 1 task(s) have custom fields that could not be verified.

Next steps

Look up a message in Fix validation errors. Field rules and defaults are in the Schema Reference, and Validation, metadata, and retired fields explains each validation rule.