Linked Data in MDXLD

MDXLD’s frontmatter is a superset of YAML-LD, which is itself a YAML serialization of JSON-LD. Both of those are other people’s work, governed elsewhere; MDXLD conforms to their model and extends it in exactly one place.

What is Linked Data?

Linked Data is a method of publishing structured data so that it can be interlinked and become more useful through semantic queries. It extends the Web by using URIs to name the relationships between things, making machine-readable data joinable across sources.

JSON-LD

JSON-LD  is a W3C Recommendation — a lightweight format for structuring and linking data:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Introduction to JSON-LD",
  "author": {
    "@type": "Person",
    "name": "John Doe"
  }
}

YAML-LD

YAML-LD is a YAML serialization of that same data model, developed in the W3C JSON-LD Community Group. It keeps JSON-LD’s @-prefixed keywords:

'@context': https://schema.org
'@type': Article
title: Introduction to YAML-LD
author:
  '@type': Person
  name: John Doe

Note the quotes. In YAML a bare @ is a reserved indicator character, so @context: has to be quoted to be valid — a small friction that already pushes YAML-LD authors toward aliasing.

Where MDXLD extends it

MDXLD uses $ where JSON-LD uses @:

$context: https://schema.org.ai
$type: Article
title: Introduction to MDXLD
author:
  $type: Person
  name: John Doe

$id and $type are not a deviation. JSON-LD 1.1 permits keyword aliasing through the context, and the JSON-LD community publishes exactly this alias set at dollar-convenience.jsonld. MDXLD’s $id and $type are that convention, not an invention of ours.

$context is the deviation, and it is a real one: @context is the single JSON-LD keyword that cannot be aliased , and an alias could not be used inside a context in any case. (Note that dollar-convenience.jsonld contains no $context entry, for exactly this reason.) MDXLD spells it $context regardless, for one mechanical reason — an MDX document compiles to ESM, @context is not a legal JavaScript identifier, and a document forced to quote '@context' has lost the very property that makes the $ set worth having. In YAML, too, a bare @ is a reserved indicator character and must be quoted.

The compatibility shim is one rename: a conforming JSON-LD processor reads MDXLD frontmatter by renaming $context to @context. User-defined keys never begin with $.

$context is always https://schema.org.ai

Unversioned, and permanently so. A binding IRI is an identity, and identities do not carry version numbers — a versioned $context URL is a defect, not a feature.

schema.org.ai is our superset of schema.org , in the same relationship MDXLD has to MDX: everything schema.org defines keeps schema.org’s meaning, and our additions sit above it.

Using it

---
$context: https://schema.org.ai
$id: https://example.com/posts/first
$type: BlogPosting
title: My First MDXLD Post
author:
  $type: Person
  name: Jane Smith
  url: https://example.com/jane
---
 
# {frontmatter.title}
 
Written by [{frontmatter.author.name}]({frontmatter.author.url})
 
Your MDX content here...

This keeps the document human-readable and machine-processable at once — and, because MDXLD is a superset, any MDX toolchain that ignores the frontmatter entirely still renders the page correctly.