Skip to content

Profile schema

This page lists each key that a profile file can hold. Speccy checks a profile against this schema when it loads the file, and speccy profile validate <file> checks one file. An unknown key is an error.

Change a profile or a check shows the common changes.

Key Type Required Meaning
key string matching ^[a-z][a-z0-9-]{0,31}$ yes The doc type. A spec doc’s frontmatter type, or a map entry in .speccy.yaml, selects the profile with this key.
name string yes The name the app shows for this doc type, such as Product Requirements Document.
version integer Speccy sets it on each save. Earlier review runs keep the version they used.
template string yes The path of the template, relative to the profile file. A doc must have each heading that ends with <!-- required -->, or with <!-- required: app --> at size app and larger (lint.required-headings).
limits object The size limits that lint checks. A key you leave out keeps its default.
links object The links a doc of this type must have.
grounding object The settings of the grounding stage.
coherence object The settings of the coherence checks.
verify object The post-build verification gate: the trace IDs it verifies, and the bounds of its repo scan.
breakdown object The rules Speccy follows when it proposes epics and work items from a Build Ready doc of this type.
trace object The trace IDs of this doc type.
waivers object Who approves a waiver, by the level of the check.
approvals object The approvals that a spec doc of this type needs.
divergence object The divergence stage: its readers and its build questions.
lint object The settings of the lint stage.
checks list of object yes The checks that a review runs besides lint. Each check has a slug, a level and a stage.

The size limits that lint checks. A key you leave out keeps its default.

Key Type Required Meaning
max_words integer The most words in the doc (lint.prose-limit). Default 8000.
max_section_words integer The most words in one section (lint.prose-limit). Default 900.
max_sentence_words integer The most words in one sentence (lint.sentence-length). Default 25.
max_code_block_lines integer The most lines in one code block (lint.asset-nudge). Default 40.
max_table_rows integer The most rows in one table (lint.asset-nudge). Default 15.

The links a doc of this type must have.

Key Type Required Meaning
upstream object The upstream link that a doc of this type needs (links.has-upstream).
children object A doc at size min_at or larger must link the bundles it covers (links.has-children).

The upstream link that a doc of this type needs (links.has-upstream).

Key Type Required Meaning
kinds list of one of implements, refines, references, supersedes yes The link kinds that count as an upstream link.
types list of string yes The profile keys that an upstream doc can have, such as prd.
required boolean When true, a doc with no upstream link and no standalone acknowledgement fails links.has-upstream. Default false.

A doc at size min_at or larger must link the bundles it covers (links.has-children).

Key Type Required Meaning
kinds list of one of implements, refines, references, supersedes yes The link kinds that count as a link to a covered bundle.
min integer The fewest links of those kinds that the doc needs. Default 1.
min_at one of feature, app, initiative yes The smallest doc size that the check applies to.

The settings of the grounding stage.

Key Type Required Meaning
enabled boolean Turns the grounding stage on. It is off by default: a review then makes no claim calls.
file_contradiction one of SHOULD, MUST The level of grounding.file-contradicts-claim: a claim that a file of the bundle contradicts. The default is SHOULD.
sources object The source policy: which domains the grounding stage accepts, their tier, their freshness period, and the claim class of a section.

The source policy: which domains the grounding stage accepts, their tier, their freshness period, and the claim class of a section.

Key Type Required Meaning
allow list of string matching ^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ When the list has a host, the grounding stage accepts sources from these hosts only.
forbid list of string matching ^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ Hosts that Speccy never accepts and never requests.
domains list of object The tier of each host pattern. A host that matches no pattern is secondary.
freshness object Days a source of that tier stays usable. Zero is no limit.
require_primary list of string The claim classes whose sources must all be primary.
classes list of object Rules that give the claims of a section a claim class, by heading path. The most specific pattern wins.
unclassified one of allow, warn, require-classification What Speccy does with a claim in a section that matches no class rule. allow does nothing, and warn adds a note to the run. require-classification drops the claim’s sources. Default allow.
Key Type Required Meaning
pattern string matching ^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ yes A host, such as example.com, or *.example.com for its subdomains.
tier one of primary, secondary yes The tier of a host that matches the pattern. The most specific pattern wins.

Days a source of that tier stays usable. Zero is no limit.

Key Type Required Meaning
primary integer Days a primary source stays usable.
secondary integer Days a secondary source stays usable.
Key Type Required Meaning
pattern string yes A heading path, with / between headings. A * segment matches one heading, and a trailing ** matches the rest. The match ignores case.
class string yes The claim class of a section that matches the pattern. The name unclassified is not a valid class.

The settings of the coherence checks.

Key Type Required Meaning
upstream_pending one of allow, block What an approved upstream request does to the verdict of the doc that asks for it. allow: the conflict waits on the linked doc and does not block. block: the conflict still blocks until the linked doc changes. The default is allow.

The post-build verification gate: the trace IDs it verifies, and the bounds of its repo scan.

Key Type Required Meaning
prefixes list of string matching ^[A-Z]{2,6}$ The trace ID prefixes that a verification run checks. Default REQ and NFR.
exclude list of string Path globs that the repo scan passes over. A list you set replaces the default, which holds vendor/**, node_modules/**, dist/**, build/**, .git/**, **/testdata/**, **/*.min.js, **/*.lock and **/*.sum.
max_file_kb integer The largest file, in KB, that the repo scan reads. Default 512.
max_mapper_files integer The most files that the model which finds code targets sees, highest ranked first. Default 200.

The rules Speccy follows when it proposes epics and work items from a Build Ready doc of this type.

Key Type Required Meaning
epic string What one epic is for this doc type. Default: one epic per outcome a user or an operator can see, never a layer of the stack.
max_trace_ids integer The largest work item, as a count of trace IDs. A larger item gets the SHOULD finding breakdown.size. Default 4.
order list of string The rules that order the items. A list you set replaces the default: a provider before its consumer, and expand before contract for an interface or a migration.

The trace IDs of this doc type.

Key Type Required Meaning
prefixes list of string matching ^[A-Z]{2,6}$ The trace ID prefixes that this doc type defines. An ID with another prefix gets trace.unknown-prefix.
cover list of string matching ^[A-Z]{2,6}$ The prefixes of upstream IDs that this doc must cover. Each such ID in an implements target needs a reference or an acknowledgement (trace.coverage).

Who approves a waiver, by the level of the check.

Key Type Required Meaning
should one of any_member, non_author, maintainer, forbidden or object The waiver policy of a SHOULD check. Default non_author.
must one of any_member, non_author, maintainer, forbidden or object The waiver policy of a MUST check. Default maintainer.

The approvals that a spec doc of this type needs.

Key Type Required Meaning
required integer How many approvals the current version needs. Default 1.

The divergence stage: its readers and its build questions.

Key Type Required Meaning
readers integer How many readers answer the build questions. Default 3.
questions object How many build questions the stage writes.
themes list of string The topics that the build questions cover, such as error handling or limits.

How many build questions the stage writes.

Key Type Required Meaning
min integer The fewest build questions. Default 0: the reviewer writes a question only where it sees a real choice. It cannot be larger than max.
max integer The most build questions. Default 20.

The settings of the lint stage.

Key Type Required Meaning
overrides map of object A level for a lint check, by slug: MUST, SHOULD, INFO, or off. The value off turns the check off.
slop_extra list of string More filler phrases for lint.slop-phrase to find, on top of its own list.
acronyms list of string matching ^[A-Z][A-Z0-9]{1,5}$ Acronyms that lint.undefined-acronym accepts with no definition, on top of the common ones. For example the labels of a team’s document kinds: POL, STN, ADR.
Key Type Required Meaning
slug string matching ^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$ yes The ID of the check: lower-case words with dots between them, such as sdd.data-model. It is unique in the profile.
level one of MUST, SHOULD, INFO yes The level of a finding. MUST blocks when material: an open MUST finding of an AI stage makes the verdict Not Build Ready only when the judge finds a material gap, where two plausible builder guesses differ in the data model, an interface, security or what the user sees. A deterministic MUST finding always blocks. SHOULD never blocks.
stage one of rubric, grounding, divergence, coherence yes The review stage that runs the check.
scope one of doc, section What the check reads. With doc, the check reads the whole doc, or the one section that section names. With section, the check runs on every section, and a waiver covers one section. Default doc.
question string The question the check asks about the doc.
pass_when string What must hold for the check to pass. A finding gives it as the fix.
waiver one of any_member, non_author, maintainer, forbidden or object Who approves a waiver of this check. It replaces waivers.should or waivers.must for this check.
sizes list of one of feature, app, initiative The doc sizes this check applies to. An empty list applies at every size.
section string The heading that a rubric check is about, such as Monitoring. The check reads that section with its subsections, and each section of the same doc that it links to by a heading anchor or names by a full heading title of two or more words. An edit to another section does not change its answer, and a waiver of it ends when that section changes. In a doc with no such heading, the check reads the whole doc, and the run notes say so. profile validate warns when no doc of the profile in the folder has the heading. The value none is reserved and names no heading: the check reads the whole doc on purpose, and profile validate and the run notes give no warning about its section.
reads list of one of upstream The other texts that a rubric check reads besides the doc. With upstream, the check also reads the spec doc of each implements or refines target, such as the PRD, and runs again when that doc changes. Use it for a check that compares the doc with its upstream doc.