Author the content. Declare the rules. Compile the result.
A Word file can contain an absent recipient address, an old placeholder, a heading in the wrong place or a legal value that does not match its required form. Those are document failures, not formatting preferences. docc moves that knowledge into a schema where it can be checked consistently.
Requirements are checked where they belong.
The selected schema decides the valid shape of one document type. The compiler checks the source against that shape and runs the type’s declared rules. The exact requirements are profile-specific; these are the kinds of guarantees a type can make.
| Layer | Question it answers | Example |
|---|---|---|
| Document marker and type | Is this actually a docc document, and which contract applies? | docc: 1 and document_type: ch_letter select a known type. |
| Frontmatter schema | Are required values present, typed and well-formed? | A Swiss postal code must be four quoted digits; an enum must be one allowed value. |
| Body structure | Does the document contain the required headings in the expected order? | A legal type can require RECHTSBEGEHREN before BEGRÜNDUNG. |
| Semantic markup | Are declared blocks, spans and intentional blanks used correctly? | A party block can require a name, date of birth and address span. |
| Named rules | Do type-specific cross-document constraints hold? | A no-placeholder rule prevents [Name] from surviving to output. |
| Schema/theme fit | Can the chosen theme render the schema’s declared styles and references? | A missing theme style is rejected before a paragraph is emitted. |
The compiler runs checks as a collection, not a queue of failures. An author should be able to correct all reported problems in a single editing pass.
Every error explains its place and its fix.
Diagnostics have a stable code, a source position and a hint. That makes the same result useful in a terminal, an editor, CI or an automated drafting loop.
brief.md:8:13: error[DOC010]: field `case_ref` has malformed value "ZG2026000" | 8 | case_ref: "ZG2026000" | ^^^^^^^^^^ court reference in the form AA.YYYY.NNN, | e.g. "ZG.2026.000"
The code is stable. A workflow can identify the class of failure without scraping prose.
The caret is in source. The author repairs the Markdown file, rather than manually patching a generated Word document.
The hint is actionable. The expected form belongs beside the error rather than in someone’s memory.
One document contract, several useful surfaces.
The build path is deliberately small. Each command exposes a different view of the same underlying document and profile.
# Validate without creating output. docc check brief.md # Build validates first, then emits the Word document. docc build brief.md # Machine-readable contract and diagnostics for tools, agents or CI. docc describe --json ch_letter docc check --json brief.md # Inspect the document's parsed facts and structure as JSON. docc read brief.md # Serve the same diagnostics while typing. docc lsp
check --json emits a result object containing ok, error and warning counts, and diagnostics. The JSON command contract keeps stdout structured so another tool can consume it without parsing decorative terminal output.
Same inputs, same document bytes.
docc emits the .docx itself. With unchanged source, schema and theme, the generated archive is byte-identical regardless of machine, clock or network. The document records its profile provenance; incidental environment state does not leak into the output.
For the full model, read the project’s philosophy and the schema reference.