Astral Forge ← Back to editor

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.

1
Open Astral Forge, and switch to Developer mode so Schema and JSON tools are visible.
2
In Open / Load, choose Structure JSON and select starter.schema.json.
3
In Open / Load, choose Data JSON and select starter.data.json.
4
Open the Data tab, choose a record, and change its fields. Use the Schema tab to customize the structure.
Prefer exploring a larger example? Use Open / Load → Examples… → Load RPG Example. It includes locations, items, classes, enemies, quests, categories, and references.

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.

  1. Use Add Collection to make another collection, or edit the starter's Items collection.
  2. Set its Path (the property name in data JSON) and Label (the name authors see).
  3. Set Item label path (for example name) and Item GUID path (for example itemGuid) for readable record choices and unique identities.
  4. Under Fields, add fields, labels, storage types, and optional defaults. Use Categories to organize related fields.
  5. 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"
          }
        }
      ]
    }
  ]
}
For a reference field, set 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.

Scope: Used by inspects references in the currently loaded dataset. Records in external imported datasets are not included in the reverse-reference list.

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.