Class ConfigSchema<T>

java.lang.Object
com.inductiveautomation.ignition.common.jsonschema.config.ConfigSchema<T>
Type Parameters:
T - the typed config model this schema describes.

public final class ConfigSchema<T> extends Object
The authoritative specification of one config object: a hand-authored JSON schema describing its structure, paired with the extraction that turns config JSON into a typed model.

The schema is authored strictly — canonical enum casing, additionalProperties: false, required members, defaults, and examples all live in the schema, so it doubles as the specification handed to an AI model. Any historical leniency (case-insensitive enum values, deprecated member aliases) belongs in the extractor, so validate(JsonElement) steers new configs toward the canonical form while fromJson(JsonObject) keeps accepting older shapes and toJson(T) emits only that canonical form.

A config type exposes its schema as a constant, pairing a schema — typically loaded from a classpath resource next to it — with one of the extraction flavors below:

public static final ConfigSchema<TimerTriggerConfig> SCHEMA =
    ConfigSchema.ofGson(
        JsonSchema.parse(
            TimerTriggerConfig.class.getResourceAsStream("timer-trigger.schema.json")),
        TimerTriggerConfig.class);

Instances are immutable and safe to share across threads. Extractors must be pure functions of their input: validate(JsonElement) also invokes them, on a copy, to surface semantic problems the schema cannot express.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Turns config JSON into a typed model.
  • Method Summary

    Modifier and Type
    Method
    Description
    fromJson(com.inductiveautomation.ignition.common.gson.JsonObject config)
    Deserializes a config object into its typed model.
    static <T> ConfigSchema<T>
    of(JsonSchema schema, ConfigSchema.Extractor<T> extractor)
    Pairs a schema with a hand-written extractor, for a config carrying a semantic rule the schema cannot express:
    static <T> ConfigSchema<T>
    ofGson(JsonSchema schema, Class<T> configType)
    Pairs a schema with Gson-driven extraction: the config is checked for the schema's required members, then deserialized into configType — typically a record — exactly as written.
    static <T> ConfigSchema<T>
    ofGsonWithDefaults(JsonSchema schema, Class<T> configType)
    Pairs a schema with Gson-driven extraction that first deep-merges the config over the schema's default values: the merged config is checked for the schema's required members, then deserialized into configType — typically a record.
    prettyJson(T config)
    Renders a typed config model as pretty-printed canonical JSON, for showing the model a config that already exists rather than one it proposed.
     
    The JSON schema describing the config object's structure.
    com.inductiveautomation.ignition.common.gson.JsonObject
    toJson(T config)
    Serializes a typed config model into the schema's canonical spelling, inverting fromJson(JsonObject).
    @Nullable ConfigProblems
    validate(com.inductiveautomation.ignition.common.gson.JsonElement config)
    Strictly validates a proposed config object, collecting every problem rather than stopping at the first.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • of

      public static <T> ConfigSchema<T> of(JsonSchema schema, ConfigSchema.Extractor<T> extractor)
      Pairs a schema with a hand-written extractor, for a config carrying a semantic rule the schema cannot express:
      ConfigSchema.of(
          JsonSchema.parse(MyConfig.class.getResourceAsStream("binding-my-type.schema.json")),
          MyConfig::extract);
      

      The extractor is responsible for the whole config: unlike the ofGson flavors, nothing checks the schema's required members or fills in its defaults first.

      Parameters:
      schema - the JSON schema describing the config's structure.
      extractor - turns config JSON into the typed config model; must be a pure function.
    • ofGson

      public static <T> ConfigSchema<T> ofGson(JsonSchema schema, Class<T> configType)
      Pairs a schema with Gson-driven extraction: the config is checked for the schema's required members, then deserialized into configType — typically a record — exactly as written. A member the config omits is left to Gson rather than filled in from the schema, keeping "unset" distinguishable from "present with the default value".

      Use ofGsonWithDefaults(JsonSchema, Class) instead when the model's canonical constructor requires every member, and of(JsonSchema, ConfigSchema.Extractor) when the config has shapes Gson cannot map directly.

      Enum members deserialize case-insensitively, preserving the leniency of the hand-written parsers this replaces.

      Parameters:
      schema - the JSON schema describing the config's structure.
      configType - the config model class Gson deserializes into.
    • ofGsonWithDefaults

      public static <T> ConfigSchema<T> ofGsonWithDefaults(JsonSchema schema, Class<T> configType)
      Pairs a schema with Gson-driven extraction that first deep-merges the config over the schema's default values: the merged config is checked for the schema's required members, then deserialized into configType — typically a record. Defaults and required-ness are read from the schema, so they are defined exactly once.

      Use this flavor when the model's canonical constructor requires every member — a record calling Map.copyOf on an optional member, say. Use ofGson(JsonSchema, Class) instead when an absent member must stay absent, and of(JsonSchema, ConfigSchema.Extractor) when the config has shapes Gson cannot map directly.

      Enum members deserialize case-insensitively, preserving the leniency of the hand-written parsers this replaces.

      Parameters:
      schema - the JSON schema describing the config's structure.
      configType - the config model class Gson deserializes into.
    • schema

      public JsonSchema schema()
      The JSON schema describing the config object's structure.
    • prettySchemaJson

      public String prettySchemaJson()
      Returns:
      the schema rendered as pretty-printed JSON, suitable for handing to the model as the authoritative config specification.
    • toJson

      public com.inductiveautomation.ignition.common.gson.JsonObject toJson(T config)
      Serializes a typed config model into the schema's canonical spelling, inverting fromJson(JsonObject). null members are omitted rather than emitted as JSON null, while an empty collection is still emitted, so "unset" and "empty" stay distinguishable.

      An absent member is not self-describing, though: it can read as "unrestricted" in a configuration that already exists but as "propose no change" in one the model produced, so a caller handing this JSON to the model has to say which of the two it is.

      Parameters:
      config - the typed config model.
      Returns:
      the config as a JSON object.
    • prettyJson

      public String prettyJson(T config)
      Renders a typed config model as pretty-printed canonical JSON, for showing the model a config that already exists rather than one it proposed. Such a config need not be one validate(JsonElement) would accept — an editor can hold real states the schema forbids in a proposal — so callers should label it as current state.
      Parameters:
      config - the typed config model.
      Returns:
      the config as pretty-printed JSON.
    • validate

      public @Nullable ConfigProblems validate(com.inductiveautomation.ignition.common.gson.JsonElement config)
      Strictly validates a proposed config object, collecting every problem rather than stopping at the first. Structural problems are found by the schema; when the config is structurally clean, the extractor runs too — on a copy — so semantic rules the schema cannot express (path parseability, cross-member constraints) are checked against the same code that parses the config at runtime.

      Intended for authoring-time consumers — AI assistants, schema-driven editors, tests. The runtime deserialization path is fromJson(JsonObject), which is deliberately more lenient.

      Parameters:
      config - the proposed config object.
      Returns:
      every problem found, or null when the config is acceptable.
    • fromJson

      public T fromJson(com.inductiveautomation.ignition.common.gson.JsonObject config) throws ConfigurationException
      Deserializes a config object into its typed model. This is the runtime path: the extractor runs directly, preserving its historical leniencies, and the schema is only consulted when extraction fails — turning the raw error into a path-qualified diagnosis.
      Parameters:
      config - the config object to parse.
      Returns:
      the typed config model.
      Throws:
      ConfigurationException - if the config cannot be parsed; the message lists the schema violations that explain the failure when there are any.