MDXLD: MDX + Linked Data

MDXLD (MDX with Linked Data) extends MDX with semantic web patterns, enabling you to create documents that are both human-readable and machine-processable.

What is MDXLD?

MDXLD adds three special frontmatter fields to MDX:

$type: The semantic type of the document (e.g., BlogPost, Service, Person)
$id: A unique identifier URL (e.g., https://example.com/posts/hello-world)
$context: The JSON-LD context for semantic interpretation (optional)

These fields follow JSON-LD patterns, making your MDX documents part of the semantic web.

Basic Example

---
$type: BlogPost
$id: https://blog.example.com/posts/getting-started
$context: https://schema.org
title: Getting Started with MDXLD
author:
  $type: Person
  $id: https://example.com/authors/jane
  name: Jane Developer
  email: [email protected]
date: 2025-10-27T12:00:00Z
tags: [mdx, linked-data, tutorial]
---

# Getting Started with MDXLD

This document is both human-readable and machine-processable.

The $.Subject.predicate.Object Pattern

MDXLD enables the $.Subject.predicate.Object pattern central to Business-as-Code:

// Access semantic data programmatically
import { $ } from 'sdk.do'

// Query by type
const blogPosts = await $.BlogPost.find({ status: 'published' })

// Access by ID
const post = await $.BlogPost.get('https://blog.example.com/posts/getting-started')

// Navigate relationships
const author = await post.author.get()

The $ symbol represents the root of the semantic graph, Subject is the type (BlogPost), predicate is the action (find, get), and Object is the result.

.org.ai Ontologies

MDXLD integrates with 70+ .org.ai ontologies that provide semantic types for various domains:

schema.org.ai

The largest ontology with 817 types and 1,518 properties from Schema.org:

---
$type: schema.org.ai/Product
$id: https://products.example.com/widget-x
$context: https://schema.org
name: Widget X
brand:
  $type: schema.org.ai/Brand
  name: Acme Corp
offers:
  $type: schema.org.ai/Offer
  price: 99.99
  priceCurrency: USD
---

# Widget X

A high-quality widget from Acme Corp.

onet.org.ai

Occupational data with 105,816 entities from O*NET:

---
$type: onet.org.ai/Occupation
$id: https://onet.org.ai/15-1252.00
code: 15-1252.00
title: Software Developers, Applications
tasks:
  - $id: https://tasks.org.ai/xxx
    description: Design and develop software applications
skills:
  - $id: https://skills.org.ai/programming
    name: Programming
---

# Software Developer

Career information for software developers.

gs1.org.ai

Global product identification standards:

---
$type: gs1.org.ai/Product
$id: https://products.example.com/widget-x
gtin: '00012345678905'
glnLocation: '0614141000005'
productName: Widget X
---

# Widget X

Product with GS1 identifiers for global supply chain tracking.

Installation

pnpm install mdxld

Quick Start

import { parseMDXLD, validateSchema } from 'mdxld'
import { z } from 'zod'

// Parse MDXLD document
const parsed = parseMDXLD(mdxContent)
console.log(parsed.frontmatter.$type)
console.log(parsed.frontmatter.$id)

// Validate against schema
const BlogPostSchema = z.object({
  $type: z.literal('BlogPost'),
  $id: z.string().url(),
  title: z.string(),
  author: z.object({
    name: z.string(),
    email: z.string().email(),
  }),
})

const validated = validateSchema(parsed.frontmatter, BlogPostSchema)

Key Features

Semantic Types: Use $type to define document types from ontologies
Global IDs: Use $id for globally unique identifiers
Schema Validation: Validate documents against Zod schemas
JSON-LD Conversion: Convert between MDX and JSON-LD
Relationship Extraction: Build knowledge graphs from links
Wikilink Support: Bidirectional relationships via wikilinks
Ontology Integration: 70+ .org.ai ontologies included

Use Cases

Service Definitions: Define Cloudflare Workers with semantic types
Product Catalogs: Store products with schema.org validation
Knowledge Bases: Create interconnected documentation
API Documentation: Generate type-safe API docs
Content Management: Query content like a database

mdxld