Home Getting Started Human Spec LLM Spec

Validate a Spec

Check that your MAPI document is well-formed and follows the specification. Catch structural issues before they cause problems downstream.

Validation methods

MAPI is designed to be validated easily—by humans, LLMs, or automated tools:

  • Manual review — Use the checklist below against your document
  • LLM validation — Give an LLM the validator reference card and your spec
  • Automated tools — Coming soon (community contributions welcome)

LLM-assisted validation

The validator reference card teaches an LLM exactly what to check. It will catch structural issues, invalid transport strings, missing required sections, and more.

MAPI Validator Reference Card

Raw markdown for LLM consumption — validation rules and error patterns
Fetch this page: https://markdownapi.org/specs/MAPI-VALIDATOR.md

Or paste this prompt directly into your LLM chat

Prompt 
# Instructions

Validate the following MAPI document against the rules in the
validator reference card. Report any issues found, organized by:

1. Document-level issues (missing title, metadata, etc.)
2. Capability-level issues (per capability)
3. TypeScript syntax issues (in code blocks)

For each issue, explain what's wrong and how to fix it.

# MAPI Validator Reference Card

[Paste MAPI-VALIDATOR.md here]

# MAPI Document to Validate

[Paste your .mapi.md file here]

Quick checklist

Run through this manually for a quick sanity check:

Validation Checklist

Document Level

File has .mapi.md extension
Starts with # Title (H1 heading)
Has document ~~~meta block with version, base_url, auth
Has at least one ## Capability: section

Per Capability

Has ~~~meta block with id and transport
Transport matches pattern: HTTP METHOD /path or WS /path
Has ### Intention with non-empty prose
Has ### Input if method expects body (POST/PUT/PATCH)
Has ~~~response 200 or ### Output
TypeScript blocks have valid syntax

Common issues

These come up frequently, especially with LLM-generated specs:

  • Missing HTTP prefix — Transport should be HTTP POST /path, not just POST /path
  • Weak Intentions — "Creates a user" doesn't help; explain when and why
  • Constraints in wrong place — field: string required isn't valid TypeScript; use field: string; // required
  • Response without status — Use ~~~response 200, not just ~~~response
  • Over-documenting errors — Standard errors (400, 401, 500) should use > Errors: standard (...)
Iterative fixing

After validation, ask the LLM to "fix all the issues you found and output the corrected MAPI document." It's usually faster than fixing manually.

Next steps

Have an LLM write a spec Export to OpenAPI Write another spec