Craft

Changing a type

A schema change is a change to every file of the type. Saving a new schema doesn't rewrite any file: each one keeps the content it had. Each section below is one kind of change and what it does to those files.

Where the change is made decides whether the files must fit first:

  • In the app or through Orbit, saving a schema checks no file. Files that no longer fit show up the next time they are written (see later writes).
  • A push from a CLI workspace checks every file of the type, the ones not in the workspace too, and refuses the change if any file fails, naming each file and field. Fix those files in the same push: the check judges the files as the push leaves them, counting its updates and deletes.

Add a field

Safe. Existing files don't have it until someone fills it in, and its default is not applied to them: a default only fills new files. A new required field is a different change (below).

Remove a field

The values stay in every file that had them. They are no longer shown or checked, but they are still there. To clear them, write each file without the field. A computed field that read the removed one is refused when the schema is saved, until it is changed too.

Rename a field

To change only the name people see, set the field's title: one edit, and every file keeps its value. A key inside an object field (a skill in skills) shows by its key on the sheet, so renaming it means renaming the key and moving each file's value. A rename is a removed field plus a new one: files keep their values under the old name, and the new field starts empty. Move each file's value to the new name. Computed fields that read the old name must be changed in the same save, and the schema editor offers to do it for you. When you rewrite the files anyway, rename the key to match the new name. Afterwards, tell the creator the old field is gone and how many files' values moved (none, when no file had one). A layout that shows the field follows the rename when the schema change comes without a new layout.

Make a field required

Files without a value for it no longer fit, and its default doesn't fill them (a default only fills new files). Fill it in on every file in the same change.

Change a field's type or shape

A value in the old shape no longer fits: text that is now a number, one reference that is now a list. Convert each file's value in the same change.

Tighten limits or change choices

A lower maximum, a shorter length, fewer enum values or a renamed value leaves files outside the new limits. Find them and change their values. Enum values must match exactly here: "Rare" in a file doesn't fit a list that now says "rare".

Change the layout only

Safe. A layout changes how files look, never what they hold, and no file is checked. See layouts.

Later writes to a file that doesn't fit

A file left outside the schema keeps working until it is written again. What happens then depends on the write:

  • A change to some of its fields (the GM recording damage, an agent changing one value) must leave those fields valid. Old problems elsewhere in the file are let through.
  • Writing the whole file again, including pushing it from a workspace, must fit the schema.
  • Saving it in the app's file editor is never refused for not fitting, so the problem stays.

Fix files when you change the schema rather than leaving them for later.

Rename the type

To rename a type, change its name on the type's General tab. The type's slug changes with its name, and so does the type part of its files' names. Reference fields and filters on other types name it by its old slug and are not changed for you: change them to the new slug. References stored in files keep working, because they hold the target's id.

Change the designation

Saving the type in the app adds the voice field to a character type and removes it from any other. Making a type one of the fixed types (game_start, script) replaces its name and schema with the fixed ones and drops its layout and creation flow. Files' designation data, such as a place's map, is not moved or converted. See designations.

Change the content type

Files are not converted between Markdown and JSON. Change the content type only on a type with no files, or move each file's content yourself.

Delete the type

To delete a type, delete it from the File Types tab. It is refused while the type has any files: delete them first.

Go back to an earlier version

Every save keeps a version of the whole type. To go back, open the type's Version History tab and restore the version you want. The name, schema, layout, creation flow and settings all go back together, and no file changes: files written for the newer schema keep their content. See file type versions.