How to run mif-validate and convert a document

This guide runs the deterministic mif-validate gate on a document and converts it between Markdown and JSON-LD. The verdict carries no language model — it is the canonical schema plus a lossless round-trip, so identical input yields an identical answer every time. For the full description of the skill, see the mif-validate reference.

Step 1 — Validate at a level

Pick the MIF level the document targets and run the validator:

node scripts/mif-validate.mjs your-doc.md --level 1

The level overlay layers required fields on top of the canonical schema: L1 is the floor (id + type + created); L2 additionally requires namespace, modified, and temporal; L3 additionally requires provenance and temporal.validFrom. A RESULT: VALID at MIF L<n> line means the document is schema-conformant and its round-trip is lossless.

Step 2 — Read the failure when it fails

A non-zero exit names the cause: 1 is a schema, level, or round-trip failure; 2 is a usage error (no file given). Schema failures print the exact JSON pointer that broke, for example /citations/0/citationRole must be equal to one of the allowed values — fix that field and re-run.

Step 3 — Convert to JSON-LD

Project the document to its machine form. The converter schema-checks the input first unless you pass --no-check:

node scripts/mif-convert.mjs emit-jsonld your-doc.md

Step 4 — Confirm the round-trip is lossless

The round-trip is the heart of the “one artifact, two readers” guarantee: the Markdown a person reads and the JSON-LD a parser resolves must carry the same information both ways. Check it explicitly:

node scripts/mif-convert.mjs roundtrip your-doc.md

A round-trip OK (lossless md<->jsonld) line confirms no information is lost in either direction.

Step 5 — Skip the round-trip only when you must

If you are validating a fragment whose round-trip you do not need, pass --no-roundtrip to mif-validate to check schema and level alone. Prefer the full check for any document you ship — losslessness is what makes the two readers equivalent. To author a document from scratch and then validate it, follow the validate-and-author how-to.