Note: This is an active fork of rsek/datasworn. See Fork Status below.
Datasworn provides game rules, assets, moves, and oracles from the Ironsworn family of tabletop RPGs in a structured JSON format, along with TypeScript typings and JSON schemas.
This is a pre-release. Until v1.0, breaking changes may occur on any version bump.
For the original Datasworn JSON files, see the legacy branch.
Note: The official npm packages are outdated and missing schema changes from 2024. See Using this Fork below for how to use the latest version.
npm install @datasworn/core
npm install @datasworn/starforged
npm install @datasworn/ironsworn-classic
npm install @datasworn/ironsworn-classic-delveThe official npm packages haven't been updated since before rsek's last commits. This fork includes schema changes that make JSON files incompatible with the old npm validator. To use this fork in your project instead:
{
"dependencies": {
"@datasworn/core": "github:tbsvttr/datasworn#main&path:pkg/nodejs/@datasworn/core"
}
}{
"dependencies": {
"@datasworn/core": "github:tbsvttr/datasworn/pkg/nodejs/@datasworn/core"
}
}Available packages in pkg/nodejs/:
@datasworn/core- TypeScript typings and JSON schema@datasworn/starforged- Starforged data@datasworn/ironsworn-classic- Classic Ironsworn data@datasworn/ironsworn-classic-delve- Delve expansion data@datasworn/ironsworn-classic-lodestar- Lodestar expansion data (moves only)
Pydantic V2 packages with full type safety:
uv add datasworn-core datasworn-starforgedAvailable packages: datasworn-core, datasworn-classic, datasworn-delve, datasworn-starforged, datasworn-sundered-isles
Community content: datasworn-community-content-starsmith, datasworn-community-content-ancient-wonders, datasworn-community-content-fe-runners
See pkg/python/README.md for details.
Type definitions for C#, Go, Java, Ruby, and Rust are available in the json-typedef directory, generated from JSON TypeDef schemas.
JSON schemas and data are in the datasworn directory.
| Package | Description |
|---|---|
@datasworn/core |
TypeScript typings and JSON schema |
@datasworn/ironsworn-classic |
Original Ironsworn rulebook data |
@datasworn/ironsworn-classic-delve |
Ironsworn: Delve expansion data |
@datasworn/ironsworn-classic-lodestar |
Ironsworn: Lodestar expansion data (moves only) |
@datasworn/starforged |
Ironsworn: Starforged data, SVG icons, WEBP images |
| Package | Description | Author |
|---|---|---|
sundered_isles |
Starforged: Sundered Isles expansion | Shawn Tomkin |
starsmith |
Starsmith Expanded Oracles | Eric Bright |
fe_runners |
Fe-Runners cyberpunk expansion | Craig Smith |
ancient_wonders |
Ancient Wonders expansion (oracles, assets, moves)* | Ludic Pen |
* Included with permission from Ludic Pen
This fork continues active development while the original repository is inactive. Changes include:
| Feature | Status |
|---|---|
| TypeBox 0.34+ compatibility | Fixed |
| Security dependency updates | Applied |
| TypeScript strict mode | Full compliance |
| Starsmith Expanded Oracles | Added |
| Fe-Runners (cyberpunk expansion) | Added |
| Sundered Isles expansion | Added |
| Ancient Wonders expansion | Added |
| Lodestar moves (Ironsworn Classic) | Added |
| Python/Pydantic packages | Added |
| Rust/JTD type generation (#78) | Fixed |
| Trigger condition IDs | Added (v0.0.6) |
This fork maintains compatibility for potential future reconciliation:
upstream-mainbranch preserves original repo statefork-basetag marks the divergence point- Commit style follows original conventions
Remotes:
origin -> tbsvttr/datasworn (this fork)
upstream -> rsek/datasworn (original)
Tags:
fork-base -> commit where fork diverged
upstream-snapshot-2024 -> upstream state at time of fork
- Bun 1.3+ (required)
- jtd-codegen (optional, for multi-language types)
- Rust (optional, for Rust integration tests)
# Install jtd-codegen via Homebrew (macOS)
brew install jsontypedef/jsontypedef/jtd-codegen
# Install Rust via asdf (recommended) or rustup
asdf plugin add rust
asdf install rust latestNote: The published npm packages work with both Node.js and Bun. Bun is only required for building from source.
git clone https://github.com/tbsvttr/datasworn.git
cd datasworn
bun install| Command | Description | Requirements |
|---|---|---|
bun run build |
Full build (all steps) | jtd-codegen |
bun run build:schema |
Generate JSON schemas | - |
bun run build:jtd |
Generate multi-language types | jtd-codegen |
bun run build:dts |
Generate TypeScript types | - |
bun run build:json |
Build game data JSON | - |
bun run build:pkg |
Build npm packages | - |
bun run test |
Run all tests | Rust (optional) |
bun run test:build |
Run build validation tests | Rust (optional) |
bun run check |
TypeScript type check | - |
bun run viewer |
Launch interactive data viewer | - |
Browse the data online at tbsvttr.github.io/datasworn
If you don't need multi-language type definitions (C#, Go, Java, Python, Ruby, Rust), you can skip jtd-codegen and run individual build commands instead of bun run build.
The test suite includes Rust integration tests that verify the generated types can deserialize all JSON data. These tests are automatically skipped if cargo is not installed.
The json-typedef/datasworn.jtd.json schema is auto-generated from TypeBox definitions in src/schema/. TypeBox schemas use [JsonTypeDef] annotations to control JTD output:
date: Type.String({
format: 'date',
[JsonTypeDef]: { schema: JtdType.String() },
})The build process:
bun run build:jtdrunssrc/scripts/json-typedef/index.ts- TypeBox schemas are converted to JTD format via
toJtdRoot() - Output is written to
json-typedef/datasworn.jtd.json jtd-codegenthen generates types for Go, Rust, Python, Java, C#, Ruby
datasworn/
├── src/
│ ├── schema/ # TypeBox schema definitions
│ ├── pkg-core/ # Core runtime (IdParser, validators)
│ ├── scripts/ # Build scripts
│ ├── tests/ # Test suite
│ └── types/ # Generated TypeScript types
├── pkg/
│ ├── nodejs/ # npm package sources
│ └── python/ # Python/Pydantic packages
├── datasworn/ # Generated JSON output
├── json-typedef/ # Generated type definitions (multi-language)
│ └── rust-test/ # Rust integration test project
├── source_data/ # YAML source files
└── tools/
└── viewer/ # Interactive data browser
Every Datasworn object has a unique _id property for referencing. ID formats:
| Type | Example |
|---|---|
| Move | move:starforged/adventure/face_danger |
| Oracle | oracle_rollable:starforged/core/action |
| Asset | asset:starforged/path/empath |
| Asset Ability | asset.ability:starforged/path/empath.0 |
| Trigger Condition | move.condition:starforged/adventure/face_danger.0 |
| Move Outcome | move.outcome:starforged/adventure/face_danger.strong_hit |
| Embedded Move | asset.ability.move:starforged/path/archer.0.craft_projectiles |
| Oracle Row | oracle_rollable.row:starforged/core/action.1-2 |
The IdParser class in @datasworn/core provides utilities for parsing, validating, and looking up objects by ID. See pkg/nodejs/@datasworn/core/README.md for usage.
- Language-agnostic JSON schema as source of truth
- Support for both Ironsworn and Starforged
- Type definitions for multiple languages
- Interchange format for homebrew/3rd party content
- Localization-friendly structure
- Every object addressable via unique ID
- Core package (typings, JSON schema, tooling): MIT
- Game content (rulebook text, images): CC-BY-4.0 or CC-BY-NC-4.0
Licensing information is embedded in the _source property throughout the data.
Originally created by rsek, now maintained as a community fork.
Special thanks to XenotropicDev for data from TheOracle.
Contributions welcome! Please:
- Open an issue to discuss significant changes
- Follow existing code style
- Include tests for new functionality
- Update documentation as needed