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. For the full description of the skill, see the mif-validate reference; for why the projection is deterministic, see One Artifact, Two Readers.

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

A RESULT: VALID at MIF L<n> line means the document is schema-conformant and its round-trip is lossless. See the mif-validate reference for exactly which fields each level requires.

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

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 (see One Artifact, Two Readers for why). To author a document from scratch and then validate it, follow the validate-and-author how-to.