Generate JSON Schema

Added in version vNext.

Generates a JSON Schema (Draft-07) document describing the structure of your game data.

Unlike the source code generation commands, this one produces a single document instead of a directory of files, and it has no language, class name or optimization options.

The generated schema describes the game data file as a whole: the root object with its Collections map, and one definitions entry per schema in your project. The --kind parameter selects which document is described - the game data itself, a patch for it, a file to import, or the formula expression tree stored in Formula properties. Use it to:

  • Validate exported game data in CI or in an asset pipeline with any JSON Schema validator (ajv, jsonschema, Json.Schema.Net).

  • Generate models in languages Charon has no SDK for, with tools like quicktype, json-schema-to-typescript, NSwag or OpenAPI Generator. Such tools consume the #/definitions/* entries, and every object in the schema carries the name of its Charon type, so the generated classes come out named after your schemas instead of after the properties they were found under.

  • Get editor support while editing game data by hand, by pointing a $schema key or an IDE schema mapping at the generated file.

  • Share the data format with another team or tool without shipping the data itself.

  • Review data model changes by regenerating the schema and diffing it.

The schema does not replace validation: formulas, reference resolution and uniqueness rules can’t be expressed in JSON Schema.

Command

# local game data (windows)
dnx dotnet-charon -- GENERATE JSONSCHEMA \
  --dataBase "c:\my app\gamedata.json" \
  --output "c:\my app\gamedata.schema.json"

# remote game data
dnx dotnet-charon -- GENERATE JSONSCHEMA \
  --dataBase "https://charon.live/view/data/My_Game/develop/" \
  --output "./gamedata.schema.json" \
  --credentials "<API-Key>"

Parameters

--dataBase

Absolute or relative path to game data. Use quotation marks if your path contains spaces.

# local file
--dataBase "c:\my app\gamedata.json"

# remote server
--dataBase "https://charon.live/view/data/My_Game/develop/"
--credentials

The API key used to access remote server in case of –dataBase being URL.

--title

Title of the root schema. By default, it is the name of the game data file.

--title "My Game Data"
--kind

Which document the schema describes.

# a complete game data file, as written by an export or a backup (default)
--kind gameData

# a patch, as written by DATA CREATEPATCH and read by DATA APPLYPATCH
--kind patch

# a file to be imported with DATA IMPORT
--kind import

# the parsed formula expression tree stored in Formula properties
--kind formulaAst

patch keys each collection by document id, where a null document deletes it and a null collection deletes every document in it, and makes every property optional and nullable.

import also makes every property optional - a document may be partial for an update or complete for a create - and accepts every value form the importer converts, so an Integer property takes 12, 12.0, "12" or true, and a reference takes a bare id.

formulaAst is the same for every project, so it needs no --dataBase:

dnx dotnet-charon -- GENERATE JSONSCHEMA --kind formulaAst --output ./formula.schema.json
--output

Destination of the generated schema. It can be a file path, out for standard output (default), err for standard error, or null to discard the result. An existing file is overwritten.

# file
--output "./gamedata.schema.json"

# standard output (default)
--output out

This command supports universal parameters.

Validating game data

Any JSON Schema validator accepts the generated document. For example, with ajv-cli:

dnx dotnet-charon -- GENERATE JSONSCHEMA \
  --dataBase ./gamedata.json \
  --output ./gamedata.schema.json

npx ajv-cli validate --spec=draft7 --strict=false \
  -s ./gamedata.schema.json \
  -d ./gamedata.json

The same works for a patch or an import file, with the matching --kind:

dnx dotnet-charon -- GENERATE JSONSCHEMA \
  --dataBase ./gamedata.json \
  --kind patch \
  --output ./gamedata.patch.schema.json

npx ajv-cli validate --spec=draft7 --strict=false \
  -s ./gamedata.patch.schema.json \
  -d ./changes.patch

--strict=false is needed because the schema annotates numbers with int32, float and similar formats, which ajv doesn’t know by default.

See also