Document schemas

Every JSON file the engine, editor, Shinra or Kaji read is a document kind: a file with a kind tag (com.hikari.material), an integer version, and a shape described by a JSON Schema (draft 2020-12) rendered from the Zig type that parses it. The rendered files live in src/hikari/schemas/ and are staged into every project as <project>/.engine/schemas/ by the editor when it opens the project (the folder is derived output under the ignored .engine/; a fresh clone has it after the first editor open). Read the schema before writing a document by hand or from an agent; the editor, the cook and the MCP tools all check against it.

What exists

Kinds today: scene, prefab, material (with the embedded material graph), model document, particle system, animation graph, sprite atlas, UI document, localization catalog, import-settings sidecar (.shinmeta.json), project descriptor, plugin package and project plugins, gameplay tags, and the nine configs/*.json documents.

The envelope

An envelope fragment (add the document-specific fields):

{
  "$schema": "../../.engine/schemas/com.hikari.material.v1.schema.json",
  "kind": "com.hikari.material",
  "version": 1
}

• kind and version are required. version is a positive integer matching the registry’s current version. Older and newer versions are refused.
• $schema is a hint the editor stamps (relative path to the staged copy). Every reader ignores it.
• Two kinds allow an implied envelope as part of their authoring format: localization catalogs and .shinmeta.json sidecars read as version 1 when the envelope is absent, and the editor stamps it on save.
• The sidecar's wire shape is assets/meta/sidecar_json.zig, mirroring what Shinra reads. The inspector's field table is a projection of it: a comptime lock refuses a row that names no wire field and a wire leaf with no row (or waiver), and a Shinra test validates what serde writes against the schema. An inspector save overlays its rows onto the file as it is on disk, so hand-authored blocks it does not model (material_overrides, spatial_clusters) survive.

Who checks what

Where shapes live

The Zig struct std.json parses is the schema. Reflection turns fields into properties, a field without a default into a required property, ?T into an optional-or-null property, enums into enum lists and [N]T into fixed-length arrays. Three declarations add what reflection cannot see:

pub const Document = struct {
    kind: []const u8,
    version: u32,
    capacity: u32 = 65_536,
    emitters: []const Emitter,

    pub const schema_doc = "GPU particle system.";                       // object description
    pub const schema_additional_properties = false;                        // default; true allows extra keys
    pub const schema_meta = .{                                             // per-field constraints
        .capacity = .{ .description = "Total particles.", .minimum = 1 },
        .texture = .{ .format = "asset-ref" },
    };
};

A type with its own jsonParse provides pub fn jsonSchema(arena) !std.json.Value. A table-driven shape (the import-settings sidecar, the UI node vocabulary) builds its body from the same table the editor uses. Every document struct must be named: an anonymous struct's type name is numbered per compilation and would make the rendered file unstable.

The binding table is src/hikari/src/assets/document_schemas.zig; the registry is sdk/src/document_schema/registry.zig. Shinra embeds the rendered files through its build.rs and classifies with shinra::schema; Kaji reads them through DocumentKinds.

Adding a kind

1. Add a registry row (sdk/src/document_schema/registry.zig): tag, suffix / fixed file / bare tag, current = 1, envelope policy, cooked suffix if Shinra cooks it.
2. Bind it (assets/document_schemas.zig): the Zig struct, optional extra_defs.
3. Render: from src/hikari, zig build generate-document-schemas, and commit schemas/.
4. If Shinra cooks it, add the AuthoringKind variant and its cook; the schema::tests bijection test refuses a mismatch. If the editor lists it, map it in editor_content.diskKindOf.

The tests refuse a registry row without a binding, a stale rendered file, an anonymous document struct, and a Shinra kind set that differs from the registry's cooked rows.

Changing a shape

• Adding an optional field with a default keeps the version. Re-render; the stale-file test tells you when.
• Removing, renaming or retyping a property bumps current. Update authored documents and regenerate the schema in the same change. Every reader accepts only the current version (or an implied envelope where allowed); there is no migration chain or compatibility range.

Game data

Game tables read through hi.json are not registry kinds, but hi.json.schema(T, allocator, .{ .id, .title }) renders the same JSON Schema for a game's own table type, so a project can publish shapes for its content://…json files the same way.