CLI

# 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](https://hotcfg.run/docs/guides/schemas). 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" }
  }
}
```

**TypeScript:**

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;
}
```

**Swift:**

MobileFlags.swift

```
// 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"
    }
}
```

**Kotlin:**

MobileFlags.kt

```
// 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"),
        )
    }
}
```

**Python:**

mobile_flags.py

```
# 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]
```

**Go:**

mobile_flags.go

```
// 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](https://hotcfg.run/docs/guides/fetching) already uses (for C#, Newtonsoft.Json; see the [Unity recipe](https://hotcfg.run/docs/recipes/unity)). 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, `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](https://hotcfg.run/docs/guides/ci) for the rest of the workflow.

Last updated 17 November 2026
