Getting Started

More on mdschema language

mdschema is a schema language for validating Markdown documents. It allows you to define patterns that Markdown content must match, making it easy to validate documentation, user inputs, or structured content.

Quick Example

Here’s a simple schema and input that validates successfully:

schema.mds

# Hello

My name is `name:/\w+/`

input.md

# Hello

My name is Alice

Output:

{"name": "Alice"}

In this example:

• # Hello is literal - it must match exactly
• `name:/\w+/` is a matcher - it captures one or more word characters

Core Concepts

1. Literals

Plain Markdown text validates itself. What you write is what must match:

schema.mds

Hello World

input.md

Hello World

schema.mds

Hello World

input.md

Goodbye World

2. Matchers

Matchers use regular expressions to validate dynamic content:

schema.mds

Age: `age:/\d+/`

input.md

Age: 25

Output:

{"age": "25"}

Matcher syntax: `label:/regex-pattern/`

4. Lists

Use {min,max} to specify how many times a pattern should match. Lists can contain literals, matchers, and repetition, and can even be nested (when nested, you can continue to see where the output comes from!):

schema.mds

- `item:/\w+/`{1,3}
  - `detail:/\w+/`{1,2}

input.md

- apple
  - red
  - sweet
- banana
  - yellow

Output:

{"item":["apple","banana",{"detail":["yellow"]}]}

Validation Output

When validation succeeds, captured values are returned as JSON:

schema.mds

Name: `name:/\w+/`, Age: `age:/\d+/`

input.md

Name: Alice, Age: 30

Output:

{"name": "Alice", "age": "30"}

More on streaming

This is one of the most powerful parts of mdvalidate. If you stream input into mdvalidate, it will automatically exit the second that your input violates your schema.

We’ll talk about how list matchers work later, but

- `test:/foo/`{2,2}

Defines a matcher that matches exactly two list items. If we stream:

- f

- foo

- foo
- fo

- foo
- fob

mdvalidate can exit early (with 1) if you use --fast-fail!

Of course, if you use this setting you will not be able to get errors for the rest of the input.

This is super useful for cases where the input is expensive, like when you are requesting LLM tokens to feed into mdvalidate.

Next Steps

Explore the documentation to learn more:

• Literals - Understanding literal matching
• Matchers - Regular expression patterns
• Literal Code - Matching code blocks literally
• Repeating Matchers - Repetition with constraints
• Lists - Validating list structures