# JSON Storage Format

> Schemity stores every diagram as plain, human-readable JSON you own. Learn how the JSON storage format works and why it makes your schema diff-friendly.

Source: https://schemity.com/doc/json-storage-format/

Schemity is **database design software with JSON storage**: each connection - its schema, layout, views, and annotations - is saved as one plain JSON file on your disk. There is no proprietary binary format and no cloud database holding your work hostage.

## Why does Schemity store diagrams as JSON?

A binary or cloud format locks your schema inside someone else's tool. JSON does the opposite:

- **Readable** - open the file in any editor and recognize your entities.
- **Diff-friendly** - changes show up as clean line-by-line diffs in Git.
- **Portable** - the file is yours, with no export step required.
- **Scriptable** - other tooling can read it if you ever need it to.

## What is in the JSON file?

One connection's JSON captures everything the diagram contains:

- **ents** - entities and their fields, with types, keys, defaults, and constraints
- **rels** - relationships and their cardinality, referential actions, and descriptions; a [virtual relation](https://schemity.com/doc/virtual-relations/) is a foreign key flagged `virtual`, and an inferred one also records that it was inferred
- **legends** - annotation boxes
- **contextViews** - every context view, with its included entities, layout, and routing
- **templates** - reusable field templates
- **logs** - a change history of the diagram
- **conn** - the connection metadata (engine, naming convention, host, and so on)

## Where are the diagram files stored?

A local workspace lives at `~/schemity/<workspace-id>/`, with a small `meta.json` and one `<connection-id>.json` per connection. If you import a workspace into a Git repository, those same files live in the folder you chose.

## Are database passwords stored in the JSON file?

Database and SSH passwords are never written to the JSON. Schemity stores them in your operating system's keychain, so you can safely commit and share the diagram files.

## How do I move a diagram between the desktop app and Schemity Lite?

Both use the same JSON file, so a diagram moves in either direction without converting anything:

1. **Export** - open the export menu and choose **Schemity JSON**. It writes the same document the app saves, without editor-only state.
2. **Import** - in the other app, open the diagram list and click **Import diagram JSON** (or right-click the blank space under the list), then pick the file.

Importing never overwrites anything. If the workspace already has a diagram with that ID or name, the import takes the next free one and the existing diagram is left alone.

The connection travels with the file in a limited way:

- **Into the desktop app** - the connection details come along, but the password fields are empty, because passwords live in the keychain, never in the file. Edit the connection to enter them before connecting.
- **Into Lite** - the connection is dropped and the diagram becomes design-only, because the browser cannot connect to a database.

A typical round trip is to sketch a schema in Lite, export it, import it into the desktop app, then attach a connection to create the tables. On the desktop you can also copy the exported file straight into a workspace folder.

## Own your data

Because the source of truth is a file you control, Schemity stays **database design software with no cloud**. Back it up, move it between machines, or keep it on an air-gapped laptop - the diagram goes wherever the file goes.

## Next

Put the file to work in [Version Control in Git](https://schemity.com/doc/version-control-git/).