Quest Schema Requirements

Every quest JSON file must conform to the quest schema to be loaded by DSPACE. Review the Quest Development Guidelines for design tips and the Quest Submission Guide when you're ready to publish. This page summarizes the required structure.

Top-level properties

Field	Type	Required	Description
`id`	string	✔️	Unique quest identifier, e.g. `astronomy/constellations`
`title`	string	✔️	Display name for the quest
`description`	string	✔️	Short summary shown before starting
`image`	string	✔️	Path to quest image asset
`npc`	string	✔️	NPC image or identifier shown in dialogue
`start`	string	✔️	ID of the first dialogue node
`dialogue`	array	✔️	Ordered list of dialogue nodes
`hardening`	object	✔️	Content rating and safety metadata for the quest
`rewards`	array	❌	Items granted on completion
`requiresQuests`	array	❌	Quest IDs that must be finished first

Dialogue nodes

Each entry in dialogue is an object with:

Field	Type	Required	Description
`id`	string	✔️	Node identifier used by `start` and `goto`
`text`	string	✔️	Dialogue text displayed to the player
`options`	array	❌	Player choices available at this node

Options

Options control quest flow and may grant or require items.

Field	Type	Required	Description
`type`	string	✔️	`goto`, `process`, or `finish`
`text`	string	✔️	Option label shown to the player
`goto`	string	depends	Target node when `type` is `goto`
`process`	string	depends	Process ID when `type` is `process`
`requiresItems`	array	❌	Items that must be owned to choose the option
`grantsItems`	array	❌	Items granted when selected
`requiresGitHub`	boolean	❌	Option requires GitHub authentication

Item arrays consist of objects with id (string) and count (number). Built-in quest files should reference images under /assets/quests/ to satisfy repository validation checks.

For a full example, see the Quest Template Example. To validate a quest file locally, run:

node scripts/validate-quest.js path/to/quest.json

That script checks the JSON schema, the required hardening metadata, and references to quest and process IDs. Repository CI also validates built-in quest files with tests like tests/builtinQuestSchema.test.ts and tests/questPrerequisites.test.ts.