xdbml-tmlanguage

TextMate grammar for the xDBML language.

xDBML is a unified, open markup language for describing the shape of structured and semi-structured data, plus the declarative metadata attached to that shape across heterogeneous storage technologies.

This repository hosts the standalone grammar so that downstream tools which expect a single-purpose grammar repo can reference it as a Git submodule or via direct fetch. Examples:

• Custom Shiki integrations: any Shiki consumer (VitePress, Astro, Slidev, custom apps) can load this grammar at runtime via loadLanguage().
• VS Code extensions: can embed this grammar in their syntaxes/ directory. The official xDBML extension does exactly that.
• Future: targeted as the grammar source for GitHub Linguist and shikijs/textmate-grammars-themes once xDBML adoption is sufficient. See "Upstream integrations" below.

Files

• xdbml.tmLanguage.json: the grammar itself. Standard TextMate format, with scope names following the <scope>.xdbml convention.

Identity

• Language name: xdbml
• Scope name: source.xdbml
• File extension: .xdbml

Using the grammar

With Shiki

import { createHighlighter } from 'shiki'
import xdbmlGrammar from 'https://raw.githubusercontent.com/xdbml/xdbml-tmlanguage/main/xdbml.tmLanguage.json' assert { type: 'json' }

const highlighter = await createHighlighter({
  themes: ['github-dark'],
  langs: [xdbmlGrammar]
})

const html = highlighter.codeToHtml(source, { lang: 'xdbml', theme: 'github-dark' })

In a VitePress config

import xdbmlGrammar from '../path/to/xdbml.tmLanguage.json' with { type: 'json' }

export default defineConfig({
  markdown: {
    languages: [xdbmlGrammar as never]
  }
})

As a Git submodule

git submodule add https://github.com/xdbml/xdbml-tmlanguage.git vendor/xdbml-grammar

Source of truth

The canonical source of the grammar lives in the xdbml-spec repository under tools/textmate/, where it is generated from parser/src/keywords.ts via a build script. The copy in this repo is published from there.

This separation lets downstream tools treat the grammar as a small, dedicated reference repo without pulling in the entire xDBML specification, parser, and playground.

How the grammar is kept in sync

When the canonical grammar in xdbml-spec changes:

1. The new xdbml.tmLanguage.json is generated by running tools/textmate/scripts/build.mjs in the spec repo.
2. The result is committed to xdbml-spec (under tools/textmate/) and to this repo (at the root).
3. Tagged releases of this repo correspond to xDBML spec versions.

Version numbering matches the xDBML specification version.

Identifying file content as xDBML

.xdbml files always begin with a version directive:

xdbml: 0.1

This is the canonical way to detect xDBML content even when the file extension is ambiguous (e.g. when content is pasted into a generic editor without a file association).

Coverage

The grammar covers the full xDBML v0.1 language surface: declaration keywords (Project, Container, Schema, Database, Keyspace, Namespace, Dataset, Bucket, Table, Entity, Collection, Record, Type, Edge, View, Enum, Ref, Note), structural type keywords (object, array, map, set, union, oneOf, anyOf, allOf), 51 scalar type names, 9 BSON type names, 8 setting flags, 52 setting keys, cardinality operators in references (>, <, -, <>), custom x_* extension properties, all string literal forms (single-quoted, triple-quoted, backtick-quoted, double-quoted identifiers), numeric literals, boolean and null constants, line and block comments.

Upstream integrations

Two upstream projects will eventually carry the xDBML grammar directly, removing the need for users to load it manually:

• GitHub Linguist (github-linguist/linguist) detects file languages on GitHub.com and applies syntax highlighting. Adoption gate: Linguist requires at least 200 public .xdbml files indexed by GitHub search before accepting the language. PR drafts are kept in the xdbml-spec repo for use when the threshold is reached.

• shikijs/textmate-grammars-themes (shikijs/textmate-grammars-themes) is the upstream registry for Shiki's bundled grammars. They defer to Linguist for the adoption signal, so the Shiki submission naturally follows the Linguist one.

Until those integrations land, this repo IS the distribution mechanism. Tools can reference it directly.

License

Apache-2.0. Same as the rest of the xDBML project.

Related

• xDBML specification
• xDBML on GitHub
• xDBML playground
• xDBML VS Code extension