@alpaca-software/40kdc-data 0.1.0

package/dist/schema-loader.d.ts

@@ -0,0 +1,15 @@
+import Ajv from "ajv";
+export declare const SCHEMAS_ROOT: string;
+/**
+ * Recursively find all .schema.json files under a directory.
+ */
+export declare function findSchemaFiles(dir: string): string[];
+/**
+ * Create and configure an AJV instance with all project schemas loaded.
+ * Schemas are registered by their $id so $ref resolution works across files.
+ */
+export declare function createValidator(): Ajv;
+/**
+ * Return the list of all loaded schema $id values.
+ */
+export declare function listSchemaIds(): string[];

package/dist/schema-loader.js

@@ -0,0 +1,79 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+/**
+ * Resolve the schema tree across both layouts:
+ *  - in-repo / dev: schemas live in the sibling top-level `schemas/` dir
+ *    (`../../schemas` from `dist/` or `src/`) — always the live source.
+ *  - packaged: once published, schemas are copied into the package root, so
+ *    `<pkg>/schemas` sits one level above the compiled file in `dist/`
+ *    (`../schemas`). When installed, the repo path resolves outside the
+ *    package and doesn't exist, so this branch is taken.
+ * Repo path wins when present so dev runs never read a stale `copy:schemas`
+ * artifact; the packaged copy is the fallback for installed consumers.
+ */
+function resolveSchemasRoot() {
+    const repo = resolve(__dirname, "../../schemas");
+    const packaged = resolve(__dirname, "../schemas");
+    return existsSync(repo) ? repo : packaged;
+}
+export const SCHEMAS_ROOT = resolveSchemasRoot();
+/**
+ * Recursively find all .schema.json files under a directory.
+ */
+export function findSchemaFiles(dir) {
+    const results = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            results.push(...findSchemaFiles(full));
+        }
+        else if (entry.endsWith(".schema.json")) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Create and configure an AJV instance with all project schemas loaded.
+ * Schemas are registered by their $id so $ref resolution works across files.
+ */
+export function createValidator() {
+    const ajv = new Ajv({
+        strict: false,
+        allErrors: true,
+        validateSchema: false,
+    });
+    addFormats(ajv);
+    const schemaFiles = findSchemaFiles(SCHEMAS_ROOT);
+    const schemas = schemaFiles.map((file) => {
+        const raw = readFileSync(file, "utf-8");
+        return JSON.parse(raw);
+    });
+    // Register all schemas by $id
+    for (const schema of schemas) {
+        const id = schema["$id"];
+        if (id) {
+            ajv.addSchema(schema, id);
+        }
+    }
+    return ajv;
+}
+/**
+ * Return the list of all loaded schema $id values.
+ */
+export function listSchemaIds() {
+    const schemaFiles = findSchemaFiles(SCHEMAS_ROOT);
+    const ids = [];
+    for (const file of schemaFiles) {
+        const raw = readFileSync(file, "utf-8");
+        const schema = JSON.parse(raw);
+        if (schema["$id"]) {
+            ids.push(schema["$id"]);
+        }
+    }
+    return ids;
+}

package/dist/validate.d.ts

@@ -0,0 +1,21 @@
+import type Ajv from "ajv";
+export interface ValidationError {
+    file: string;
+    index: number;
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+export interface ValidationResult {
+    totalFiles: number;
+    totalItems: number;
+    passed: number;
+    failed: number;
+    errors: ValidationError[];
+}
+/**
+ * Validate all data files matching the given glob pattern.
+ * Each data file is expected to be a JSON array; each element is validated individually.
+ */
+export declare function validateFiles(ajv: Ajv, pattern: string, cwd?: string): Promise<ValidationResult>;

package/dist/validate.js

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { glob } from "glob";
+import { resolve, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const DATA_ROOT = resolve(__dirname, "../../data");
+/**
+ * Map from data file base-name prefix to schema $id.
+ */
+const SCHEMA_MAP = {
+    factions: "https://40kdc.dev/schemas/core/faction.schema.json",
+    units: "https://40kdc.dev/schemas/core/unit.schema.json",
+    weapons: "https://40kdc.dev/schemas/core/weapon.schema.json",
+    "game-versions": "https://40kdc.dev/schemas/core/game-version.schema.json",
+    detachments: "https://40kdc.dev/schemas/core/detachment.schema.json",
+    enhancements: "https://40kdc.dev/schemas/core/enhancement.schema.json",
+    stratagems: "https://40kdc.dev/schemas/core/stratagem.schema.json",
+    "wargear-options": "https://40kdc.dev/schemas/core/wargear-option.schema.json",
+    "leader-attachments": "https://40kdc.dev/schemas/core/leader-attachment.schema.json",
+    "unit-compositions": "https://40kdc.dev/schemas/core/unit-composition.schema.json",
+    "force-dispositions": "https://40kdc.dev/schemas/core/force-disposition.schema.json",
+    "deployment-patterns": "https://40kdc.dev/schemas/core/deployment-pattern.schema.json",
+    "mission-matchups": "https://40kdc.dev/schemas/core/mission-matchup.schema.json",
+    missions: "https://40kdc.dev/schemas/core/mission.schema.json",
+    "secondary-cards": "https://40kdc.dev/schemas/core/secondary-card.schema.json",
+    "terrain-layouts": "https://40kdc.dev/schemas/core/terrain-layout.schema.json",
+    "phase-mappings": "https://40kdc.dev/schemas/enrichment/phase-mapping.schema.json",
+    "timing-flags": "https://40kdc.dev/schemas/enrichment/timing-flag.schema.json",
+    "interaction-flags": "https://40kdc.dev/schemas/enrichment/interaction-flag.schema.json",
+    abilities: "https://40kdc.dev/schemas/enrichment/ability-dsl/ability.schema.json",
+    "resource-pools": "https://40kdc.dev/schemas/enrichment/resource-pool.schema.json",
+};
+/**
+ * Determine which schema $id to use for a given data file path.
+ * Convention: the file's base name prefix (before the first dot) maps to a schema.
+ */
+function resolveSchemaId(filePath) {
+    const base = basename(filePath);
+    for (const [prefix, schemaId] of Object.entries(SCHEMA_MAP)) {
+        if (base.startsWith(prefix)) {
+            return schemaId;
+        }
+    }
+    return null;
+}
+/**
+ * Validate all data files matching the given glob pattern.
+ * Each data file is expected to be a JSON array; each element is validated individually.
+ */
+export async function validateFiles(ajv, pattern, cwd) {
+    const root = cwd ?? DATA_ROOT;
+    const files = await glob(pattern, { cwd: root, absolute: true });
+    const result = {
+        totalFiles: files.length,
+        totalItems: 0,
+        passed: 0,
+        failed: 0,
+        errors: [],
+    };
+    for (const file of files) {
+        const schemaId = resolveSchemaId(file);
+        if (!schemaId) {
+            result.errors.push({
+                file,
+                index: -1,
+                errors: [{ path: "", message: `No schema mapping found for file: ${basename(file)}` }],
+            });
+            result.failed++;
+            continue;
+        }
+        const validate = ajv.getSchema(schemaId);
+        if (!validate) {
+            result.errors.push({
+                file,
+                index: -1,
+                errors: [{ path: "", message: `Schema not found: ${schemaId}` }],
+            });
+            result.failed++;
+            continue;
+        }
+        let data;
+        try {
+            const raw = readFileSync(file, "utf-8");
+            data = JSON.parse(raw);
+        }
+        catch (err) {
+            result.errors.push({
+                file,
+                index: -1,
+                errors: [{ path: "", message: `Failed to parse JSON: ${err.message}` }],
+            });
+            result.failed++;
+            continue;
+        }
+        if (!Array.isArray(data)) {
+            result.errors.push({
+                file,
+                index: -1,
+                errors: [{ path: "", message: "Data file must be a JSON array" }],
+            });
+            result.failed++;
+            continue;
+        }
+        for (let i = 0; i < data.length; i++) {
+            result.totalItems++;
+            const valid = validate(data[i]);
+            if (valid) {
+                result.passed++;
+            }
+            else {
+                result.failed++;
+                result.errors.push({
+                    file,
+                    index: i,
+                    errors: (validate.errors ?? []).map((e) => ({
+                        path: e.instancePath || "/",
+                        message: e.message ?? "Unknown validation error",
+                    })),
+                });
+            }
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@alpaca-software/40kdc-data",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The 40kdc Warhammer 40K dataset behind a linked, typed API — find units, follow them to their weapons, abilities, phases, and factions. Also validates data against the canonical JSON Schemas.",
+  "keywords": [
+    "warhammer",
+    "warhammer-40k",
+    "40k",
+    "wargaming",
+    "dataset",
+    "tabletop",
+    "json-schema"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Tabletop-Developer-Consortium/40kdc-data/tree/main/tools#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tabletop-Developer-Consortium/40kdc-data.git",
+    "directory": "tools"
+  },
+  "bugs": {
+    "url": "https://github.com/Tabletop-Developer-Consortium/40kdc-data/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schemas/*": "./schemas/*"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md"
+  ],
+  "bin": {
+    "40kdc-validate": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "npm run codegen:data && tsc",
+    "codegen:data": "tsx src/codegen-data.ts",
+    "docs:api": "typedoc",
+    "validate": "tsx src/cli.ts validate-all",
+    "validate:core": "tsx src/cli.ts validate-core",
+    "validate:enrichment": "tsx src/cli.ts validate-enrichment",
+    "translate": "tsx src/cli.ts translate",
+    "bundle:schemas": "tsx src/bundle-schemas.ts",
+    "codegen:types": "json2ts -i ../crates/wh40kdc/schemas/bundled.schema.json -o src/generated.ts --unreachableDefinitions --bannerComment \"/* Generated from crates/wh40kdc/schemas/bundled.schema.json by 'npm run codegen:types'. DO NOT EDIT BY HAND. */\"",
+    "copy:schemas": "rm -rf schemas && cp -R ../schemas schemas",
+    "prepack": "npm run build && npm run copy:schemas",
+    "pretest": "npm run codegen:data",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "json-schema-to-typescript": "^15.0.4",
+    "tsx": "^4.0.0",
+    "typedoc": "^0.28.0",
+    "typedoc-plugin-markdown": "^4.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  }
+}

package/schemas/$defs/common.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/defs/common.schema.json",
+  "title": "40kdc Common Definitions",
+  "$defs": {
+    "entity-id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+      "minLength": 2,
+      "maxLength": 128,
+      "description": "Kebab-case identifier"
+    },
+    "edition": {
+      "type": "string",
+      "pattern": "^\\d{1,2}(th)?$",
+      "description": "Game edition, e.g. '10th' or '11'"
+    },
+    "dataslate-version": {
+      "type": "string",
+      "pattern": "^(\\d{4}-q[1-4]|[a-z0-9][a-z0-9-]*[a-z0-9])$",
+      "description": "Dataslate version: a quarterly tag (e.g. '2025-q3') or a named kebab-case slug for non-quarterly slates (e.g. 'pre-launch-provisional')"
+    },
+    "keyword": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "keyword-list": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/keyword" },
+      "uniqueItems": true
+    },
+    "stat-value": {
+      "description": "A stat that can be a fixed number or a dice expression",
+      "oneOf": [
+        { "type": "integer", "minimum": 0 },
+        { "type": "string", "pattern": "^\\d*[Dd]\\d+(\\+\\d+)?$" }
+      ]
+    },
+    "contributor-ref": {
+      "type": "string",
+      "description": "GitHub handle or '40kdc-community'"
+    },
+    "phase": {
+      "type": "string",
+      "enum": ["command", "movement", "shooting", "charge", "fight"],
+      "description": "The five official game phases. Unchanged between 10th and 11th edition — 11e reorders Pile In timing within the Fight phase but adds no top-level phase."
+    },
+    "phase-list": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/phase" },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "source-type": {
+      "type": "string",
+      "enum": ["ability", "stratagem", "enhancement", "detachment-rule", "faction-rule"],
+      "description": "Type of game element that is the source of an enrichment entry"
+    },
+    "player-turn": {
+      "type": "string",
+      "enum": ["your-turn", "opponent-turn", "either"],
+      "description": "Which player's turn this applies during"
+    },
+    "battle-size": {
+      "type": "string",
+      "enum": ["incursion", "strike-force"],
+      "description": "11e battle size, which sets the army's points limit and detachment-point budget: 'incursion' = 1000 pts / 2 detachment points; 'strike-force' = 2000 pts / 3 detachment points."
+    },
+    "force-disposition-id": {
+      "type": "string",
+      "enum": ["take-and-hold", "disruption", "purge-the-foe", "priority-assets", "reconnaissance"],
+      "description": "One of the five confirmed 11e launch Force Dispositions. Shared by force-disposition entities and the mission-matchup matrix."
+    },
+    "vec2": {
+      "type": "object",
+      "description": "A 2D point in board inches. Origin at a board corner; JSON uses y-down (downstream renderers may flip to y-up).",
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" }
+      },
+      "required": ["x", "y"],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/$defs/game-version-ref.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/defs/game-version-ref.schema.json",
+  "title": "Game Version Reference",
+  "type": "object",
+  "properties": {
+    "edition": { "$ref": "common.schema.json#/$defs/edition" },
+    "dataslate": { "$ref": "common.schema.json#/$defs/dataslate-version" }
+  },
+  "required": ["edition", "dataslate"]
+}

package/schemas/core/deployment-pattern.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/core/deployment-pattern.schema.json",
+  "title": "Deployment Pattern",
+  "description": "A deployment map: per-side deployment zones, objective positions, and (11e) per-side territory polygons. Pattern geometry carries forward unchanged from 10th edition; downstream tooling (e.g. bevy-deploy-helper) consumes this as the canonical encoding.",
+  "type": "object",
+  "$defs": {
+    "zone-shape": {
+      "description": "A zone footprint, expressed as an axis-aligned rectangle or an explicit polygon. Vertices/extent are relative to the owning element's position.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": { "const": "rectangle" },
+            "width": { "type": "number", "exclusiveMinimum": 0 },
+            "height": { "type": "number", "exclusiveMinimum": 0 }
+          },
+          "required": ["type", "width", "height"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": { "const": "polygon" },
+            "points": {
+              "type": "array",
+              "items": { "$ref": "../defs/common.schema.json#/$defs/vec2" },
+              "minItems": 3
+            }
+          },
+          "required": ["type", "points"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "side": {
+      "type": "string",
+      "enum": ["attacker", "defender"],
+      "description": "Which player a zone or territory belongs to."
+    }
+  },
+  "properties": {
+    "id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Mission pack or source the pattern originates from (e.g. 'leviathan')."
+    },
+    "description": { "type": "string" },
+    "zones": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Per-side deployment zones.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "player": { "$ref": "#/$defs/side" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+          "shape": { "$ref": "#/$defs/zone-shape" },
+          "position": { "$ref": "../defs/common.schema.json#/$defs/vec2" },
+          "color": {
+            "type": "string",
+            "pattern": "^#[0-9a-fA-F]{6}$",
+            "description": "Hex render color for the zone overlay."
+          }
+        },
+        "required": ["player", "shape", "position"],
+        "additionalProperties": false
+      }
+    },
+    "territories": {
+      "type": "array",
+      "description": "11e per-side territory polygons, mirroring the deployment-zone shape (e.g. the band between a deployment zone and the midline). Empty until authored.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "player": { "$ref": "#/$defs/side" },
+          "shape": { "$ref": "#/$defs/zone-shape" },
+          "position": { "$ref": "../defs/common.schema.json#/$defs/vec2" }
+        },
+        "required": ["player", "shape", "position"],
+        "additionalProperties": false
+      }
+    },
+    "objectives": {
+      "type": "array",
+      "description": "Objective-marker positions on the board.",
+      "items": { "$ref": "../defs/common.schema.json#/$defs/vec2" }
+    },
+    "recommended_terrain_layout_ids": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "Ids of recommended terrain-layout entities (resolved once terrain-layout data is authored).",
+      "items": { "$ref": "../defs/common.schema.json#/$defs/entity-id" }
+    },
+    "game_version": { "$ref": "../defs/game-version-ref.schema.json" }
+  },
+  "required": ["id", "name", "zones", "game_version"],
+  "additionalProperties": false
+}

package/schemas/core/detachment.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/core/detachment.schema.json",
+  "title": "Detachment",
+  "description": "A detachment option within a faction, providing a detachment rule, enhancements, and stratagems.",
+  "type": "object",
+  "properties": {
+    "id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "faction_id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "detachment_rule_id": {
+      "oneOf": [
+        { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+        { "type": "null" }
+      ]
+    },
+    "detachment_points": {
+      "oneOf": [
+        { "type": "integer", "minimum": 1, "maximum": 3 },
+        { "type": "null" }
+      ],
+      "description": "11e: the detachment-point cost (1–3) charged against the army's detachment-point budget. null when not yet assigned."
+    },
+    "force_dispositions": {
+      "type": "array",
+      "items": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+      "uniqueItems": true,
+      "description": "11e: ids of the Force Disposition entities this detachment grants. Empty until assigned."
+    },
+    "enhancement_ids": {
+      "type": "array",
+      "items": { "$ref": "../defs/common.schema.json#/$defs/entity-id" }
+    },
+    "stratagem_ids": {
+      "type": "array",
+      "items": { "$ref": "../defs/common.schema.json#/$defs/entity-id" }
+    },
+    "restrictions": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "required_keywords": { "$ref": "../defs/common.schema.json#/$defs/keyword-list" },
+            "excluded_keywords": { "$ref": "../defs/common.schema.json#/$defs/keyword-list" },
+            "notes": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        { "type": "null" }
+      ]
+    },
+    "game_version": { "$ref": "../defs/game-version-ref.schema.json" }
+  },
+  "required": ["id", "name", "faction_id", "game_version"],
+  "additionalProperties": false
+}

package/schemas/core/enhancement.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/core/enhancement.schema.json",
+  "title": "Enhancement",
+  "description": "A purchasable upgrade for a character unit, provided by a detachment.",
+  "type": "object",
+  "properties": {
+    "id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "detachment_id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "cost": { "type": "integer", "minimum": 0 },
+    "points_provisional": {
+      "type": "boolean",
+      "default": false,
+      "description": "True when the cost is carried over provisionally (e.g. seeded from a prior edition during migration) and not yet confirmed against the current dataslate."
+    },
+    "upgrade_tag": {
+      "type": "boolean",
+      "default": false,
+      "description": "11e: when true, this enhancement applies to up to `max_targets` non-character units while counting as a single Enhancement choice."
+    },
+    "max_targets": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Number of units this enhancement may be applied to. Only meaningful when `upgrade_tag` is true; defaults to 1."
+    },
+    "keyword_restrictions": { "$ref": "../defs/common.schema.json#/$defs/keyword-list" },
+    "exclusion_keywords": {
+      "oneOf": [
+        { "$ref": "../defs/common.schema.json#/$defs/keyword-list" },
+        { "type": "null" }
+      ]
+    },
+    "ability_id": {
+      "oneOf": [
+        { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+        { "type": "null" }
+      ]
+    },
+    "is_unique": { "type": "boolean", "default": true },
+    "game_version": { "$ref": "../defs/game-version-ref.schema.json" }
+  },
+  "required": ["id", "name", "detachment_id", "cost", "game_version"],
+  "additionalProperties": false
+}

package/schemas/core/faction.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/core/faction.schema.json",
+  "title": "Faction",
+  "description": "A playable faction or sub-faction.",
+  "type": "object",
+  "properties": {
+    "id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "parent_faction_id": {
+      "oneOf": [
+        { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+        { "type": "null" }
+      ]
+    },
+    "game_version": { "$ref": "../defs/game-version-ref.schema.json" },
+    "keywords": { "$ref": "../defs/common.schema.json#/$defs/keyword-list" },
+    "aliases": { "type": "array", "items": { "type": "string" } },
+    "faction_rule_id": {
+      "oneOf": [
+        { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+        { "type": "null" }
+      ],
+      "description": "Reference to the faction-wide ability (e.g., Oath of Moment)"
+    }
+  },
+  "required": ["id", "name", "game_version"],
+  "additionalProperties": false
+}