40kdc-data

Looking for 10th edition data? The 10e dataset is preserved on branch 10e-archive and tagged 10th/2025-q3. The main branch is migrating to 11th edition — see 11e-migration.md for status and the work plan.

Community-owned data schemas for Warhammer 40,000 developer tooling — and a linked, typed API over the dataset they describe.

What This Is

Two things, both community-owned:

1. The schema layer for the 40kdc ecosystem — JSON Schemas that model 40K entities so tools can exchange data. Entity IDs are the interoperability contract.
2. A ready-to-use dataset package. The whole dataset ships embedded behind an intuitive, typed API: find a unit, then walk to its weapons, abilities, the phases those abilities act in, and its faction — no database, no network, no runtime filesystem access. Same ergonomics consumers expect, available today.

import { units } from "@alpaca-software/40kdc-data";

units.find("Kharn")!.abilities
  .filter(a => a.phases.includes("fight"))
  .map(a => a.id); // ["legendary-killer", "berzerker-frenzy"]

find is diacritic- and punctuation-insensitive — 40K is played globally, so find("Kharn") resolves "Khârn the Betrayer" and find("Belakor") resolves "Be'lakor". Full API reference: tools/docs/api/.

What This Is Not

This is not a database of source rules prose. Source prose is kept outside the public dataset. The package contains structured mechanical representations, generated descriptions, stat lines, and point costs.

IP Stance

Content	Included?	Rationale
Stat lines (M, T, W, Sv, etc.)	Yes	Numerical facts
Point costs	Yes	Numerical facts
Weapon stats (A, S, AP, D)	Yes	Numerical facts
Source ability prose	No	Kept in private authoring inputs
Source rules prose	No	Kept outside the public dataset
Artwork / logos	No	Creative IP

Quick Start

Use the dataset (TypeScript / JavaScript):

npm install @alpaca-software/40kdc-data

import { units, factions } from "@alpaca-software/40kdc-data";

const kharn = units.find("Kharn");
kharn?.faction?.id;            // "world-eaters"
kharn?.weapons.map(w => w.name);
factions.find("World Eaters")?.units.length;

See tools/README.md for the full collection/link reference.

Validate data against schemas (the package also ships an AJV validator + CLI):

cd tools
npm install
npm run validate           # all data
npm run validate:core      # or just core / enrichment
npm run validate:enrichment

The package also ships a 40kdc-runner binary that implements the language-agnostic conformance runner protocol: NDJSON requests on stdin, NDJSON responses on stdout. The cross-implementation parity differ uses this to compare every port against the same corpus. It is not the recommended way to use the library — import the package directly for that — but it is the supported entry point for cross-language verification.

Schemas

Core (structural entities)

Schema	Description
faction	Playable factions and sub-factions
unit	Unit datasheets with stat profiles and points
weapon	Weapons with stat lines
game-version	Edition and dataslate tracking

Enrichment (community-authored intelligence)

Schema	Description
phase-mapping	Maps abilities to game phases
interaction-flag	Ability conflicts, combos, sequencing
ability	Structured ability definitions (DSL)

Shared Definitions

Schema	Description
common	Entity IDs, keywords, stat values
game-version-ref	Edition + dataslate reference

Ability DSL

40kdc builds community-authored structured game trees that express what abilities do. A deterministic describer renders those trees for consumers; it does not consult source prose.

An ability entry composes four primitives:

• Trigger: when it activates (phase, timing, type)
• Condition: prerequisites (recursive AND/OR/NOT tree)
• Effect: what it does (stat modifiers, re-rolls, mortal wounds, etc.)
• Scope: targeting range and duration

Effects support composition: choice (pick one of N) and sequence (ordered steps).

See schemas/enrichment/ability-dsl/ and data/enrichment/_example/abilities.example.json for examples.

Versioning

Everything is tagged to edition + dataslate (e.g., 11th/2025-q3). See VERSIONING.md.

For Tool Developers

Multiple ways to consume this repo, depending on language and use case.

The data package — npm install @alpaca-software/40kdc-data for the embedded dataset behind the linked typed API (above), plus the generated entity types and an AJV validator. This is the fastest path for most tools.

The schemas directly — for non-JS toolchains or custom pipelines:

1. Add 40kdc-data as a git submodule, or reference schema $id URLs
2. Point your JSON Schema validator (draft 2020-12) at schemas/
3. Use entity IDs from the 40kdc dataset for interoperability

Rust

The wh40kdc crate exposes serde-deserializable structs generated from these schemas (one flat module, regenerated by cargo run -p xtask -- codegen). Until it publishes to crates.io, depend on it via git:

[dependencies]
wh40kdc = { git = "https://github.com/wn-mitch/40kdc-data" }

use wh40kdc::Unit;

let units: Vec<Unit> = serde_json::from_str(&json)?;

The crate also bundles the schema as wh40kdc::BUNDLED_SCHEMA for downstream validation. The crate also ships a wh40kdc-runner binary used by the cross-implementation parity differ — see CONFORMANCE.md. Crate types are MIT; the schema content they describe is CC0.

Python

The wh40kdc package on PyPI mirrors the TypeScript API surface: Dataset linked queries, importers and exporters for all roster formats, the damage-projection cruncher and attribution, the abilities resolver, scoring, terrain geometry, the DSL/scoring describers, and a schema validator emitting the shared closed-enum error codes.

pip install wh40kdc

from wh40kdc import Dataset

ds = Dataset.embedded()
unit = ds.units.find("Khârn the Betrayer")
print([w.name for w in unit.weapons])

Entities are plain dicts (mirroring the JSON the schemas describe) behind linked views; generated TypedDicts in wh40kdc._types provide static typing. The only runtime dependency is jsonschema. The package also ships the conformance runner (python -m wh40kdc.runner) used by the cross-implementation parity differ — see CONFORMANCE.md. Package code is MIT; the schema content it describes is CC0.

Go

The wh40kdc Go module mirrors the same surface — the embedded dataset behind a linked Dataset API, all roster importers/exporters, the cruncher and attribution, the abilities resolver, scoring, terrain geometry, the DSL/scoring describers, and a schema validator emitting the shared closed-enum error codes.

go get github.com/wn-mitch/40kdc-data/go@latest

Records are modelled as plain map[string]any (mirroring the JSON the schemas describe) behind linked views; the only external dependency is golang.org/x/text (Unicode normalization for diacritic-insensitive lookup). The module ships the conformance runner (go/cmd/wh40kdc-runner) used by the cross-implementation parity differ — see CONFORMANCE.md. Module code is MIT; the schema content it describes is CC0.

R (planned)

An R package is planned, likely as an extendr wrapper around the Rust crate rather than a native port (the Rust ecosystem handles cruncher numerics and JSON parity more cleanly than R's idioms allow at the boundary). The decision is pending a wrapper prototype; the CONFORMANCE.md FAQ explains the trade-off in more detail.

Parity guarantee

All official ports — TypeScript, Rust, Python, and Go (R planned) — are held in behavioral agreement by a shared conformance corpus in conformance/. Within the documented tolerances (notably ±5e-4 per cruncher stage; byte-equal export goldens otherwise), the same inputs produce the same outputs in every language. See CONFORMANCE.md for what's pinned, the per-area invariants, and the contribution rules.

Contributors and acknowledgements

40kdc-data is sustained by people who build its schemas, author and correct its data, maintain its ports, and provide upstream community resources. Major, long-running contributions include:

• @wn-mitch — project creator and maintainer; schema and data architecture, ingestion and authoring systems, and the TypeScript, Rust, Python, and Go packages.
• Oberyn (@bmerrill17) — foundational project and data work; ability-authoring and ingestion infrastructure, canonical ability IDs, raw-text store tooling, detachment-rule reconciliation, and MFM synchronization.
• @Cmnspro — ongoing roster-legality, wargear, ability-link, and faction-asset contributions.
• @stopsign002 — repeated live-datasheet, points, wargear, and shared-unit corrections.
• @superwutz and Battlemaster — structured terrain-layout data and its public Data API, used with permission.

Many other contributors have supplied data corrections, schema improvements, tests, and tooling. GitHub's contributors page is the durable, complete record of accepted code contributions; issue reports, reviews, and community research are valued even when they do not appear there.

Licensing

Directory	License
schemas/	CC0 (public domain)
data/enrichment/	CC BY 4.0 (attribution required)
tools/	MIT + attribution (public deployments must credit)

Public deployment requirement: Any publicly accessible application or service that ships @alpaca-software/40kdc-data as part of its end-user product must display a visible credit containing the text "Powered by 40kdc-data" and a link to https://40kdc.alpacasoft.dev in a user-accessible location (footer, about page, or credits section). Private use and library redistribution are exempt. Full terms: LICENSE-TOOLS.

Contributing

See CONTRIBUTING.md.