Documentation · Getting started
From a schema to editable data
Astral Forge turns a JSON schema into a visual editor for structured project data. Start with a working pair of example files, customize the fields, then create and connect your own records.
1. Get started
Fastest option: choose Try the starter in the editor. The schema and data are loaded automatically, and the Data tab opens with editable records. Alternatively, download both starter files above and load them manually using the steps below.
starter.schema.json.starter.data.json.2. Understand the two files
Schema JSON
Describes the collections, fields, field types, defaults, and relationships that Astral Forge uses to build the editor.
starter.schema.json
Data JSON
Contains the actual records in those collections. Its schema GUID and version identify which structure it belongs to.
starter.data.json
The schemaGuid must match in both files. The data's schemaVersion should match the structure version, or the app may offer a structure update.
3. Build a schema
In Developer → Schema, edit the schema name and version, then define your collections. A collection is a group of records, such as items, materials, or quests.
- Use Add Collection to make another collection, or edit the starter's Items collection.
- Set its Path (the property name in data JSON) and Label (the name authors see).
- Set Item label path (for example
name) and Item GUID path (for exampleitemGuid) for readable record choices and unique identities. - Under Fields, add fields, labels, storage types, and optional defaults. Use Categories to organize related fields.
- Optionally configure Record Identity so new records receive automatically generated IDs.
The starter uses these schema concepts (abbreviated for readability):
{
"name": "Astral Forge Starter Items",
"schemaGuid": "72b5459a-e80e-44d5-a71b-80602633c1b3",
"schemaVersion": 1,
"collections": [
{
"path": "items",
"label": "Items",
"itemLabelPath": "name",
"itemGuidPath": "itemGuid",
"fields": [
{
"path": "itemGuid",
"label": "Item ID",
"storageType": "string",
"required": true
},
{
"path": "name",
"label": "Name",
"storageType": "string",
"default": ""
},
{
"path": "relatedItem",
"label": "Related item",
"storageType": "string",
"semantic": "reference",
"editor": "reference",
"reference": {
"collection": "items",
"valuePath": "itemGuid",
"labelPath": "name"
}
}
]
}
]
}
semantic and editor to reference, then provide the target collection and its valuePath. In the complete starter schema, the collection also defines automatic UUID-v7 record identity generation.4. Start building data
Once the schema and data are loaded, use the Data tab. Select a collection and record, edit its values, or choose + Add record. Record generation can fill IDs automatically when configured in the schema.
The starter contains these two connected records (shown without its optional schemaRef and description values):
{
"schemaGuid": "72b5459a-e80e-44d5-a71b-80602633c1b3",
"schemaVersion": 1,
"items": [
{
"itemGuid": "item-bronze-key",
"name": "Bronze Key",
"relatedItem": null
},
{
"itemGuid": "item-explorer-pack",
"name": "Explorer Pack",
"relatedItem": "item-bronze-key"
}
]
}
A record stores a reference using the target record's identifier, not its display name. Astral Forge's reference picker displays a friendly label, so authors do not need to memorize IDs.
5. Navigate references and “Used by”
To link two items, select Explorer Pack and choose Bronze Key in the Related item field. The field's Open action follows that reference.
To find incoming references, select Bronze Key in the Data view and click Used by near the record selector. The results list identifies Explorer Pack, its source collection, and the field referencing the key. Select a result to navigate to its source record.
6. Validate and save
- Select Validate in the Data view to inspect current errors.
- Use Download JSON to export your edited data file locally.
- After editing the schema in Developer mode, choose Download Schema to export the schema file as JSON. Keep it together with your data export, since both files must share a schema GUID.
- For Git-backed workflows, connect GitHub and open a repository dataset. Available submission actions depend on your repository connection and access.
Keep schema and data versions aligned when adding or renaming collection fields. The newer Validation & Editing Safety milestone will expand validation feedback and recovery tools.
7. Keep exploring
Try adding a new collection, grouping fields by category, or adding a reference between records. When you're ready for larger projects, Open / Load → Git Repository can discover compatible schema/data files on a branch.