Schema Overview

What is Igor Schema?

Igor Schema was initially created for describing game design data. Game design data describes rules and content of the game. This data is later used by the game code.

For the successful data-driven development it’s important to isolate data from code. Designers use some kind of editor to edit data, and code loads this data. It is quite common that data is stored in XML or JSON files, and designers use special editors (sometimes just simple text editors) to edit data. It helps a lot if content they create is validated against schema, e.g. XSD schema for XML files.

When Igor is used to describe types of design data, so that it can be deserialized from JSON or XML, it is natural to use Igor to generate the schema as well. This schema can be used by the data editor to enforce data validation and provide the best user experience for designers.

This is exactly what Igor Schema does - it describes the JSON serialization format of Igor data types, and provides details on data validation and editor types to be used by data editors. In particular, Igor Schema is used by Hercules tool that can edit CouchDB JSON documents containing JSON-serialized Igor records.

Igor Schema Format

Technically Igor Schema is a JSON document of a certain layout. This layout can be described with Igor language itself. This description is available here: https://raw.githubusercontent.com/igorlang/igor/refs/heads/main/source/Igor.Schema/schema.igor .

The main data type used by Igor Schema is Descriptor. Descriptor describes how a value should be edited and validated. Descriptor is a variant type, each record describes values of different types. Some types are built-in, and some types are user defined custom types described with CustomType variant. In particular, enum, record and variant custom types are supported.

Enabling Schema

By default, no type information at all is included into generated Igor Schema. You have to enable schema for modules or types via enabled attribute for schema target:

[schema enabled]
module ProtocolCards
{
    ...
}

Note

All schema related attributes should use schema target.

schema enabled attribute has scope inheritance, which means that it is enough to set it on module and it will enable schema generation for all nested types.

Cards and Schema Root

We call the single isolated piece of data, that is usually distinguished by unique name or id, a card. A card describes a single game content instance (e.g. character, item) or ruleset (e.g. game mode, mission).

Different classes of cards are described with different Igor types. Igor Schema expects that all cards are records descending from the single variant type. This type is called the root type. In order to select a proper editor for the JSON document describing a card, the variant tag field is used which we call a category.

By convention, the root variant is usually named Card, the category field is named category and category enum is named CardCategory. However this convention is not mandatory.

The root variant nust be marked with schema root attribute. The set of Igor files used to generate the schema should have one and only one root variant.

Example:

[schema enabled]
module ProtocolCards
{
    enum CardCategory
    {
        item;
        character;
        game_mode;
    }

    [schema root]
    variant Card
    {
        tag CardCategory category;
        ...
    }

    record Card.CardItem[item]
    {
        ...
    }

    ...
}

Providing More Type Information

It’s desirable to provide as much information as possible on how types and values should be edited and validated for better editor validation and user experience. This can be achieved with schema attributes.

The list of supported schema attributes is located here: Schema Attributes.

Generating Schema

You can use Igor Compiler to generate schema from the set of Igor files using the following command:

igorc.exe -schema *.igor

This command will generate schema.json file in the current folder. You can override file name with -output-file command line option. See more information on available command line options here: Command Line Options.

See also

Uploading Schema