Structured Data

The Structured Data layer of MDX provides semantic frontmatter using YAML-LD (YAML + Linked Data), enabling type-safe schemas, validation, and database storage.

Core Concepts

Document

The fundamental unit - combines YAML-LD frontmatter with content body.

---
$type: BlogPost
$id: https://example.com/posts/hello
title: Hello World
author: https://example.com/authors/jane
---

See the Document overview.

Database

Schema-first database modeling with automatic bi-directional relationships.

const db = DB({
  Post: {
    title: 'string',
    author: 'Author.posts',  // Creates both directions
  },
})

See the Database overview.

Templates (Shapes)

Templates define the shape of your data - the TypeScript type or JSON Schema that structures your content:

type StoryBrand = {
  name: string
  hero: {
    persona: string
    occupation: string
  }
  problem: {
    external: string
    internal: string
  }
}
 
type Noun = {
  name: string
  plural: string
  properties: Array<{ name: string; type: string; required: boolean }>
  actions: Array<{ name: string; returns: string }>
}

Templates enable bi-directional conversion between objects and content formats:

import { toMarkdown, fromMarkdown } from '@mdxld/markdown'
import { toJSONLD, toJSONSchema } from '@mdxld/json'
 
// Object → Formats
const markdown = toMarkdown(storyBrand)
const jsonld = toJSONLD(storyBrand)
const schema = toJSONSchema(StoryBrandType)
 
// Markdown → Object
const data = fromMarkdown<StoryBrand>(editedMarkdown)