Skip to content
mif-docs

Skill reference: mif-validate

Skill reference: mif-validate

Section titled “Skill reference: mif-validate”

The mif-validate skill is a substrate helper: it is the gate that proves a document is MIF-conformant, rather than a genre that authors prose. This reference describes what that proof consists of, how the skill produces it, when it runs, and the sources behind it.

PropertyValue
AuthorsA deterministic MIF-conformance verdict (and form conversion)
Purpose groupAuthoring helpers
MIF conceptTypesubstrate
Target MIF level3
Primary sourceMIF specification

What this document type is

Section titled “What this document type is”

mif-validate produces a verdict, not a document: a deterministic statement that a given file is — or is not — MIF-conformant at a stated level. The verdict rests on three independent checks. First, it projects the document’s frontmatter to canonical JSON-LD and validates that against the published MIF schema using Ajv under JSON Schema 2020-12. Second, it enforces the level floor — that an L1, L2, or L3 claim is backed by the fields that level requires. Third, it verifies the Markdown ↔ JSON-LD round-trip is lossless, converting the document to JSON-LD and back and asserting the result is byte-identical to the source.

That third check is what makes MIF trustworthy: it guarantees the machine projection and the human document are two views of one artifact, with nothing added or dropped in either direction. The skill also converts a document to either output form on demand, so the JSON-LD projection can be emitted for downstream tooling. It is not a linter of prose quality and not a genre author; it judges conformance and nothing else.

How the skill produces one

Section titled “How the skill produces one”

mif-validate carries the conformance procedure as durable instructions plus the validator scripts the suite runs in its gates.

  • Schema check. The JSON-LD projection is validated against the canonical schema with Ajv; any structural or enum violation fails the verdict — as the fail-closed guard does when an author writes a non-conformant block.
  • Level floor. The skill confirms the document carries every field its claimed level demands, refusing an L3 claim that lacks a provenance graph.
  • Round-trip proof. It runs the lossless Markdown ↔ JSON-LD conversion and rejects any document whose round-trip is not exact, which constrains authors to the constructs proven to round-trip.
  • Eval cases. The skill ships evals/evals.json exercising conformant and non-conformant inputs. As a substrate helper it carries no templates/ exemplars; the check-exemplars gate applies only to the genre skills, not to the validator itself.

When it is beneficial

Section titled “When it is beneficial”

Run mif-validate as the final gate after authoring or editing any MIF document, and whenever you need to emit a document’s JSON-LD form. It is the companion to mif-frontmatter: the former writes the metadata, the latter proves it. Because the verdict is deterministic, it can run in CI and block a non-conformant change automatically.

There is no genre anti-trigger — the helper validates every genre — but it is not a substitute for human review of content: a document can be perfectly conformant and still poorly written. Use it for conformance, not editorial quality.

Example

Section titled “Example”

After drafting an ADR, the author runs mif-validate at level 3. It projects the frontmatter to JSON-LD, validates it against the MIF schema, confirms the L3 provenance and citations are present, and verifies the round-trip is lossless, emitting a single VALID verdict — or a precise list of failures to fix.

Provenance & citations

Section titled “Provenance & citations”