hotcfg types

Generate the types your app decodes config into from the bin's JSON Schema, in TypeScript, Swift, Kotlin, Java, Python, PHP, Ruby, Go, GDScript or C#.

usage
hotcfg types --lang <language> (--bin <bin_id> | --schema <file.json>) [-o <file>] [--check]

Writes the types your app decodes config into, from the bin's JSON Schema. The schema already checks every publish, so the server can't serve the wrong shape. Generated types extend that check to your code: a renamed key or a changed type shows up as a compile error where the app reads it, not as a crash after release.

terminal
$ hotcfg types --bin acme/mobile-flags --lang swift -o App/MobileFlags.swift
✓ Wrote Swift types to App/MobileFlags.swift
  from     bin acme/mobile-flags
  type     MobileFlags

Needs CLI 0.3.0 or later (C#: 0.5.0). With --bin it needs a secret key that can access the bin. With --schema it reads a local file and makes no network request. Without -o, the code goes to standard output.

An example

For this schema:

schema.json
{
  "type": "object",
  "required": ["kill", "limits"],
  "properties": {
    "kill": {
      "type": "object",
      "description": "Features to turn off.",
      "additionalProperties": { "type": "boolean" }
    },
    "limits": {
      "type": "object",
      "required": ["max_upload_mb"],
      "properties": { "max_upload_mb": { "type": "integer" } }
    },
    "theme": { "enum": ["light", "dark"] },
    "banner": { "type": "string" }
  }
}
mobileFlags.ts
// Generated by hotcfg types from the JSON Schema of bin acme/mobile-flags.
// Do not edit: run hotcfg types again when the schema changes.

export interface MobileFlags {
  /** Features to turn off. */
  kill: Record<string, boolean>;
  limits: Limits;
  theme?: "light" | "dark";
  banner?: string;
}

export interface Limits {
  max_upload_mb: number;
}

Languages

Each language gets one file with no dependencies, beyond what its fetch code already uses (for C#, Newtonsoft.Json; see the Unity recipe). Decode the config your fetch code returns:

Language--langYou getDecode with
TypeScripttypescript, tsInterfaces (types only, nothing checked at run time)const config: MobileFlags = await res.json()
SwiftswiftCodable structsJSONDecoder().decode(MobileFlags.self, from: data)
Kotlinkotlin, ktData classes, read with org.json (built into Android)MobileFlags.fromJson(text)
JavajavaRecords (Java 17 or later)MobileFlags.fromMap(map), from the Map your JSON library parses (Jackson, Gson, ...)
Pythonpython, pyTypedDict classes (Python 3.11 or later)config: MobileFlags = json.loads(text)
PHPphpReadonly classes (PHP 8.1 or later)MobileFlags::fromArray(json_decode($json, true))
Rubyruby, rbData classes (Ruby 3.2 or later)MobileFlags.from_h(JSON.parse(text))
GogoStructs with json tagsjson.Unmarshal(body, &config)
GDScriptgdscript, gdClasses (Godot 4)MobileFlags.from_dict(JSON.parse_string(text))
C#csharp, csClasses for Newtonsoft.Json: in Unity, the com.unity.nuget.newtonsoft-json package; elsewhere, the Newtonsoft.Json NuGet packageMobileFlags.FromJson(text)

In Swift, Kotlin, Java, PHP and C#, a missing required key or a value of the wrong type fails the decode with an error; in Ruby, a missing required key does. Handle it like any other bad response, by keeping the config you had. TypeScript, Python and Go types aren't checked when decoding: they rely on the schema, which already checked what the bin serves.

Java needs the file named after the top-level type, here MobileFlags.java, and keeps the other types nested inside it (MobileFlags.Limits). Ruby does the same (MobileFlags::Limits), and so does GDScript, as inner classes of the class_name script.

Flags

FlagDefaultDescription
--langnoneThe language, from the table above. Required.
--binnoneUse this bin's schema: an id, or org-slug/id.
--schemanoneUse a schema file instead. Give exactly one of --bin and --schema.
--namefrom the binThe top-level type's name. mobile-flags gives MobileFlags; with --schema, the schema's title or the file's name.
--packagenoneThe Go, Kotlin or Java package, PHP or C# namespace, or Ruby module. Go defaults to config.
-o, --outstdoutWrite to this file.
--checkoffDon't write anything: fail if the file named by -o isn't what would be generated. For CI.

From schema to types

  • Required properties are plain fields. The rest are optional: ? in TypeScript and Swift, nullable in Kotlin and Java, a pointer in Go, NotRequired in Python, nullable (?) in C#, null when missing in PHP, Ruby and GDScript. "type": ["string", "null"] is nullable too.
  • Objects with properties become named types, named after the property (limits gives Limits), its $defs entry, or its title. The items of an array are named in the singular: overrides holds Override.
  • Objects with only additionalProperties become maps from string keys to that type, and so do objects with only patternProperties: a map of what the patterns allow.
  • Enums of strings are unions of the values in TypeScript and Python ("light" | "dark"). Elsewhere they are strings, with the values in a comment. An app built before you added a value then still decodes the new one, and can treat it as unknown.
  • $ref inside the schema (#/$defs/..., #/definitions/..., or an $anchor such as #thing) and allOf work, including types that refer to themselves. References to other files or URLs are refused.
  • oneOf and anyOf of different types are unions in TypeScript and Python. Other languages have no such type, so the field holds any JSON value, and the command prints a warning naming the field.
  • Tuples (prefixItems, or items as a list) are arrays of any JSON value, with a warning.
  • Integers are 64-bit. An integer whose minimum or maximum is beyond that range gets a warning, since larger values won't decode.
  • if/then/else, not and dependentSchemas don't change the types: a property they make required in some cases stays optional. Publishing still checks them.

Keys that aren't valid names in the language are renamed (max_upload_mb is maxUploadMb in Swift, Kotlin, Java and PHP, and MaxUploadMb in Go and C#). The decoding code still reads the original key.

Changing the schema later

Generated types ignore keys they don't know. So adding a property to the schema never breaks an app that's already out, and the new types are for the next build. Removing a required property, or changing its type, breaks the builds that read it: add the new property next to the old one, and remove the old one once those builds are gone.

In CI

Commit the generated file, and fail the pull request when it's out of date with the bin's schema:

step
- uses: hotcfg/action@v1
  with:
    command: install

- name: Types are up to date
  env:
    HOTCFG_API_KEY: ${{ secrets.HOTCFG_API_KEY }}
  run: hotcfg types --bin acme/mobile-flags --lang swift -o App/MobileFlags.swift --check

When they differ, the step fails with the file and how to fix it, and on GitHub Actions the file is annotated in the pull request:

job log
error: App/MobileFlags.swift is out of date with the schema of bin acme/mobile-flags
hint: run the same command without --check, and commit the file

--check accepts a file checked out with Windows line endings. See Config from CI for the rest of the workflow.

Last updated 17 November 2026