Class ConfigSchema<T>
- Type Parameters:
T- the typed config model this schema describes.
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 ClassesModifier and TypeClassDescriptionstatic interfaceTurns config JSON into a typed model. -
Method Summary
Modifier and TypeMethodDescriptionfromJson(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'srequiredmembers, then deserialized intoconfigType— 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'srequiredmembers, then deserialized intoconfigType— 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.schema()The JSON schema describing the config object's structure.com.inductiveautomation.ignition.common.gson.JsonObjectSerializes a typed config model into the schema's canonical spelling, invertingfromJson(JsonObject).@Nullable ConfigProblemsvalidate(com.inductiveautomation.ignition.common.gson.JsonElement config) Strictly validates a proposed config object, collecting every problem rather than stopping at the first.
-
Method Details
-
of
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
ofGsonflavors, nothing checks the schema'srequiredmembers 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
Pairs a schema with Gson-driven extraction: the config is checked for the schema'srequiredmembers, then deserialized intoconfigType— 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, andof(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
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'srequiredmembers, then deserialized intoconfigType— 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.copyOfon an optional member, say. UseofGson(JsonSchema, Class)instead when an absent member must stay absent, andof(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
The JSON schema describing the config object's structure. -
prettySchemaJson
- Returns:
- the schema rendered as pretty-printed JSON, suitable for handing to the model as the authoritative config specification.
-
toJson
Serializes a typed config model into the schema's canonical spelling, invertingfromJson(JsonObject).nullmembers 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
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 onevalidate(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
nullwhen 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.
-