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#.
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.
$ 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 MobileFlagsNeeds 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:
{
"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" }
}
}// 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;
}// Generated by hotcfg types from the JSON Schema of bin acme/mobile-flags.
// Do not edit: run hotcfg types again when the schema changes.
struct MobileFlags: Codable, Sendable {
/// Features to turn off.
let kill: [String: Bool]
let limits: Limits
/// One of "light", "dark".
let theme: String?
let banner: String?
}
struct Limits: Codable, Sendable {
let maxUploadMb: Int
enum CodingKeys: String, CodingKey {
case maxUploadMb = "max_upload_mb"
}
}// Generated by hotcfg types from the JSON Schema of bin acme/mobile-flags.
// Do not edit: run hotcfg types again when the schema changes.
import org.json.JSONObject
data class MobileFlags(
/** Features to turn off. */
val kill: Map<String, Boolean>,
val limits: Limits,
/** One of "light", "dark". */
val theme: String? = null,
val banner: String? = null,
) {
companion object {
/** Parses the config's JSON text. */
fun fromJson(json: String): MobileFlags = fromJson(JSONObject(json))
fun fromJson(o: JSONObject): MobileFlags = MobileFlags(
kill = o.getJSONObject("kill").let { m0 -> m0.keys().asSequence().associateWith { k0 -> m0.getBoolean(k0) } },
limits = Limits.fromJson(o.getJSONObject("limits")),
theme = if (o.isNull("theme")) null else o.getString("theme"),
banner = if (o.isNull("banner")) null else o.getString("banner"),
)
}
}
data class Limits(
val maxUploadMb: Long,
) {
companion object {
fun fromJson(o: JSONObject): Limits = Limits(
maxUploadMb = o.getLong("max_upload_mb"),
)
}
}# Generated by hotcfg types from the JSON Schema of bin acme/mobile-flags.
# Do not edit: run hotcfg types again when the schema changes.
# Needs Python 3.11 or later.
from __future__ import annotations
from typing import Literal, NotRequired, TypedDict
class Limits(TypedDict):
max_upload_mb: int
class MobileFlags(TypedDict):
# Features to turn off.
kill: dict[str, bool]
limits: Limits
# One of "light", "dark".
theme: NotRequired[Literal["light", "dark"]]
banner: NotRequired[str]// Generated by hotcfg types from the JSON Schema of bin acme/mobile-flags.
// Do not edit: run hotcfg types again when the schema changes.
package config
type MobileFlags struct {
// Features to turn off.
Kill map[string]bool `json:"kill"`
Limits Limits `json:"limits"`
// One of "light", "dark".
Theme *string `json:"theme,omitempty"`
Banner *string `json:"banner,omitempty"`
}
type Limits struct {
MaxUploadMb int64 `json:"max_upload_mb"`
}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 | --lang | You get | Decode with |
|---|---|---|---|
| TypeScript | typescript, ts | Interfaces (types only, nothing checked at run time) | const config: MobileFlags = await res.json() |
| Swift | swift | Codable structs | JSONDecoder().decode(MobileFlags.self, from: data) |
| Kotlin | kotlin, kt | Data classes, read with org.json (built into Android) | MobileFlags.fromJson(text) |
| Java | java | Records (Java 17 or later) | MobileFlags.fromMap(map), from the Map your JSON library parses (Jackson, Gson, ...) |
| Python | python, py | TypedDict classes (Python 3.11 or later) | config: MobileFlags = json.loads(text) |
| PHP | php | Readonly classes (PHP 8.1 or later) | MobileFlags::fromArray(json_decode($json, true)) |
| Ruby | ruby, rb | Data classes (Ruby 3.2 or later) | MobileFlags.from_h(JSON.parse(text)) |
| Go | go | Structs with json tags | json.Unmarshal(body, &config) |
| GDScript | gdscript, gd | Classes (Godot 4) | MobileFlags.from_dict(JSON.parse_string(text)) |
| C# | csharp, cs | Classes for Newtonsoft.Json: in Unity, the com.unity.nuget.newtonsoft-json package; elsewhere, the Newtonsoft.Json NuGet package | MobileFlags.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
| Flag | Default | Description |
|---|---|---|
--lang | none | The language, from the table above. Required. |
--bin | none | Use this bin's schema: an id, or org-slug/id. |
--schema | none | Use a schema file instead. Give exactly one of --bin and --schema. |
--name | from the bin | The top-level type's name. mobile-flags gives MobileFlags; with --schema, the schema's title or the file's name. |
--package | none | The Go, Kotlin or Java package, PHP or C# namespace, or Ruby module. Go defaults to config. |
-o, --out | stdout | Write to this file. |
--check | off | Don'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,NotRequiredin Python, nullable (?) in C#,nullwhen missing in PHP, Ruby and GDScript."type": ["string", "null"]is nullable too. - Objects with
propertiesbecome named types, named after the property (limitsgivesLimits), its$defsentry, or itstitle. The items of an array are named in the singular:overridesholdsOverride. - Objects with only
additionalPropertiesbecome maps from string keys to that type, and so do objects with onlypatternProperties: 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. $refinside the schema (#/$defs/...,#/definitions/..., or an$anchorsuch as#thing) andallOfwork, including types that refer to themselves. References to other files or URLs are refused.oneOfandanyOfof 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, oritemsas a list) are arrays of any JSON value, with a warning. - Integers are 64-bit. An integer whose
minimumormaximumis beyond that range gets a warning, since larger values won't decode. if/then/else,notanddependentSchemasdon'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:
- 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 --checkWhen 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:
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