Configuration schema reference

Every EdgeCommons component is driven by a single JSON config document that is validated against one canonical JSON Schema. That schema is shared, byte-for-byte, across all four SDKs (Java, Python, Rust, TypeScript) — there is no language-specific config dialect. This page is the exhaustive field reference: for every section it lists each field’s type, default, allowed values, and meaning, exactly as declared in the schema.

This is a data reference, not an API reference. For how to read the document from component code — typed accessors, change listeners, hot reload — see the config API reference and the Configuration guide.

Where the schema lives

The single source of truth is schema/edgecommons-config-schema.json (JSON Schema draft-07). Each library embeds a generated copy (libs/java/.../resources/, libs/python/edgecommons/resources/, libs/rust/resources/, libs/ts/src/config/schema.json). Never hand-edit a per-library copy — edit the canonical file, then run the sync script to propagate it. CI fails on drift.

Linux

./schema/sync-schema.sh           # copy canonical schema into libs/{java,python,rust,ts}
./schema/sync-schema.sh --check   # the drift gate CI runs

Windows

.\schema\sync-schema.ps1          # copy canonical schema into libs/{java,python,rust,ts}
.\schema\sync-schema.ps1 --check  # the drift gate CI runs

Validation policy

Validation is fail-closed in every language: a missing schema or any validation failure is a hard error at startup, never a silent skip. The public entry points are ConfigurationValidator.validate (Java/Python), edgecommons::config::validation::validate (Rust), and validate (TypeScript / Ajv).

The top level is strict: additionalProperties: false and required: ["component"]. An unknown or mistyped top-level key is rejected. Each named section (logging, metricEmission, messaging, streaming, credentials, parameters, health, and the rest) is also strict — additionalProperties: false with fully-described fields.

The subsystem sections are strict, not permissive

The canonical schema fully describes every section with additionalProperties: false. Only a few nested subtrees are genuinely open for arbitrary keys: component.global and each component.instances[] entry (arbitrary component-specific keys), plus the kafka sink properties map. tags and logging.loggers accept any matching key but constrain the value (string / level enum). Everything else rejects unknown keys.

Hierarchical config layers

The schema validates the effective document after hierarchical layering. Raw catalog node layers and raw component layers are allowed to be partial fragments, so they are not validated independently. After the SDK deep-merges layers[].config, the merged document must satisfy the strict schema below.

The CONFIG_COMPONENT transport wrapper is not itself a schema document. It must contain lineageVersion: 1, a catalogVersion, a requested component, and a non-empty layers array. Only each layer’s config object participates in the effective document.

component is the only required section

component is the single required top-level key. Every other section is optional, and the newer subsystems are opt-in: the matching accessor returns null / None / undefined (and the subsystem stays dormant) unless its config section is present. The thirteen top-level sections are:

Section	Purpose
logging	Console + optional rotated file logging, per-logger levels, per-language format.
metricEmission	Where metrics go (log / messaging / CloudWatch / Prometheus) and target tuning.
heartbeat	The UNS state keepalive + the sys system-measures metric.
tags	Custom template variables for paths and topics (also stamped as envelope tags).
hierarchy	The UNS enterprise-hierarchy declaration (ordered level names, device last).
identity	The UNS identity values for the levels above the device.
topic	UNS topic-building options (includeRoot).
component (required)	Your component’s own config — global and per-instance.
messaging	Dual-MQTT broker config (local + optional generic northbound MQTT) and the request deadline.
streaming	High-rate telemetry streams to Kinesis/Kafka via the embedded buffer.
credentials	Encrypted local vault + optional central sync from AWS Secrets Manager.
parameters	Offline-first externalized config (env / mountedDir / AWS SSM).
health	Kubernetes HTTP health/readiness endpoint.

Numbers vs integers

A field typed integer in the schema — heartbeat.intervalSecs, health.port, logging.fileLogging.backupCount, logging.publish.maxRecordBytes, logging.publish.queue.maxRecords, and the MQTT/Prometheus ports — requires a whole number, but accepts any numeric encoding of one: 5000, 5000.0, and 5e3 are the same value. A fractional value in one of these fields is rejected. Fields typed number accept fractional values.

Whatever the encoding in the source document, every SDK delivers integral numbers to your component in integer form. See Numbers in configuration.

Precedence and platform defaults

Many defaults are not fixed constants — they depend on the resolved platform. Every defaultable setting follows one rule:

resolve(setting) = explicit config field  ▸  platform-profile default  ▸  library default

That is: an explicit value in your config always wins; if absent, the active platform profile supplies a default; if the profile has none, the library’s built-in default applies. The platform is GREENGRASS, HOST, or KUBERNETES (auto-detected unless you pass --platform). The settings that differ by platform:

Setting	GREENGRASS	HOST	KUBERNETES	Library default
metricEmission.target	(none)	(none)	prometheus	log
metric-log path (metricEmission.targetConfig.logFileName)	(none)	local path *	local path *	/greengrass/v2/logs/{ComponentFullName}.metric.log
logging format (logging.<lang>_format)	(none)	(none)	json (stdout-JSON sink)	console/text
health.enabled	false	false	true	false
credentials.vault.keyProvider.type	(none)	(none)	env	file

* The local metric-log path constant is ./logs/{ComponentFullName}.metric.log in Java, Rust, and TypeScript, but ./logs/{ComponentFullName}_metric.log (underscore, not dot) in Python — a real cross-language divergence to be aware of when scraping metric logs from a HOST/Kubernetes run.

Two platform-default nuances

The KUBERNETES credentials default only changes the default key-provider type — it never auto-enables credentials; the credentials section must already be present. And in the Rust SDK the prometheus Kubernetes default is feature-gated: it applies only with the metrics-prometheus cargo feature, otherwise Rust falls back to log with a warning. Java/Python/TS apply prometheus unconditionally.

logging

Console logging plus optional size-rotated file logging. Object, strict.

Field	Type	Default	Allowed values	Meaning
level	string	INFO	TRACE, DEBUG, INFO, WARN, ERROR, FATAL	Root logger level.
java_format	string	(none)	—	Log4j2 PatternLayout. Applied only by Java; other SDKs ignore it.
python_format	string	(none)	—	logging.Formatter string. Applied only by Python.
rust_format	string	(none)	—	Token format ({timestamp} {level} {component}/{componentName} {target} {message}). Applied only by Rust.
ts_format	string	(none)	—	Token format ({timestamp} {level} {logger} {message}). Applied only by TypeScript.
fileLogging	object (strict)	—	—	Rotated file logging (below); requires enabled.
fileLogging.enabled	boolean	false	—	Enable file logging.
fileLogging.filePath	string	(none)	—	Log file path (supports template variables).
fileLogging.maxFileSize	string	10MB	e.g. 512KB, 10MB, 1GB	Size at which the file rotates.
fileLogging.backupCount	integer (min 0)	5	—	Number of rotated backups to keep.
loggers	object	—	keys ^[a-zA-Z0-9._-]+$ → level enum	Per-logger level overrides.
globalControl	boolean	false	—	Apply logging config to the whole application, not just EdgeCommons.
publish	object (strict)	—	—	Optional library-owned UNS log publisher. Disabled by default.
publish.enabled	boolean	false	—	Publish structured log records to the reserved UNS log class.
publish.destination	string	local	local, northbound	Send log records on the local transport or configured northbound transport.
publish.minLevel	string	INFO	TRACE, DEBUG, INFO, WARN, ERROR, FATAL	Minimum level captured or published.
publish.captureNative	boolean	true	—	Capture the SDK-wired logging framework where supported.
publish.captureConsole	boolean	false	—	Request stdout/stderr or console capture where supported by the SDK/runtime.
publish.maxRecordBytes	integer (min 1)	8192	—	Maximum serialized log record body size before truncation.
publish.queue.maxRecords	integer (min 1)	1000	—	Maximum queued log records, drop-oldest on overflow.
publish.queue.onFull	string	dropOldest	dropOldest	Queue overflow policy.
publish.redaction.enabled	boolean	true	—	Redact common credential-like strings before publishing.
publish.redaction.replacement	string	***	—	Replacement text for redacted matches.
publish.redaction.extraPatterns	array[string]	[]	regex strings	Additional redaction regexes.

Each library reads only its own <lang>_format key and ignores the other three. The case-insensitive token json in a <lang>_format field selects the structured stdout-JSON sink — it is the default on the KUBERNETES platform.

When enabled, logging.publish emits edgecommons.log.v1 records on ecv1/{device}/{component}/log/{level} through the library’s reserved-publish seam. Public component publishes to the log class remain rejected.

metricEmission

Where metrics are sent, plus target-specific tuning. Object, strict.

Field	Type	Default	Allowed values	Meaning
target	string	log	log, messaging, cloudwatch, cloudwatchcomponent, prometheus	Metric destination. prometheus is pull-based (in-process registry exposed as OpenMetrics over HTTP) and is the KUBERNETES default.
namespace	string	edgecommons	—	CloudWatch namespace.
largeFleetWorkaround	boolean	false	—	Enable the large-fleet emit workaround.
targetConfig	object (strict)	—	—	Target-specific config (below).

metricEmission.targetConfig

Several fields here have no schema default; the library default is shown in parentheses (and is applied in code, not by the schema).

Field	Type	Default	Allowed values	Meaning
logFileName	string	(code: /greengrass/v2/logs/{ComponentFullName}.metric.log)	—	File for the log target (template variables). Overridden to a local path on HOST/Kubernetes — see Precedence.
maxFileSize	string	(code: 10MB)	—	Rotation size for the log target.
destination	string	(code: ipc)	ipc, local, northbound	Destination for the messaging target. ipc/local = local transport; northbound = configured northbound broker.
intervalSecs	integer (min 1)	(code: 5)	—	Batch flush interval for the cloudwatch target.
port	integer (1–65535)	9090	—	HTTP port for the prometheus target.
path	string	/metrics	—	OpenMetrics exposition path for the prometheus target.
buffer	object (strict)	—	—	Durable store-and-forward buffer for the cloudwatch target (below).

Messaging metric topic

The messaging target publishes to the fixed UNS metric topic ecv1/{device}/{component}/metric/{metricName}, and the cloudwatchcomponent target always uses the external AWS contract topic cloudwatch/metric/put. See the Unified Namespace.

metricEmission.targetConfig.buffer

Durable disk buffer that lets the cloudwatch target survive long cloud disconnects (drains via a host-callback PutMetricData sink).

Field	Type	Default	Allowed values	Meaning
type	string	durable	durable, memory	durable = edgestreamlog disk buffer + callback drain; memory = in-memory batching.
path	string	(code: /var/lib/edgecommons/metrics/{ComponentName}/cw)	—	Buffer directory (durable only; template variables).
maxDiskBytes	number (min 0)	134217728 (~128 MiB)	—	Maximum on-disk backlog in bytes.
onFull	string	dropOldest	dropOldest, block, rejectNew	Behavior when the buffer reaches maxDiskBytes.
fsync	string	perBatch	perBatch, interval, always	Durability flush policy.

heartbeat

The library-owned heartbeat: a UNS state keepalive published to ecv1/{device}/{component}/state each tick (body {"status":"RUNNING","uptimeSecs":n}, a best-effort {"status":"STOPPED"} on graceful shutdown), with the enabled system measures emitted as the metric sys through the metric subsystem. Object, strict.

Field	Type	Default	Allowed values	Meaning
enabled	boolean	true	—	Whether the heartbeat (state keepalive + sys measures metric) runs.
intervalSecs	integer (min 1)	5	—	Heartbeat interval in seconds.
measures	object (strict)	—	—	Which system measures the sys metric includes (below).
destination	string	local	local, northbound	Publish destination of the state keepalive only. The measures route through metricEmission.

Heartbeat state topic

The keepalive topic is always the component’s UNS state topic. heartbeat.destination selects only the publish destination for that state message; system measures route through metricEmission. See the Heartbeat guide.

heartbeat.measures

Availability of individual measures varies by language and platform.

Field	Type	Default	Meaning
cpu	boolean	true	Include CPU usage.
memory	boolean	true	Include memory usage.
disk	boolean	false	Include disk usage (not on all platforms/languages).
threads	boolean	false	Include thread count.
files	boolean	false	Include open-file count.
fds	boolean	false	Include file-descriptor count (not on all platforms/languages).

tags

Object whose keys match ^[a-zA-Z0-9_-]+$ and whose values are strings. Each tag becomes a custom template variable: a tag site is usable as {site} in any templated path or topic (alongside the built-ins {ComponentName}, {ComponentFullName}, and {ThingName}). Tags are also stamped as the message envelope’s tags element (business context — the enterprise location lives in hierarchy/identity, not here). Unknown-shaped keys are rejected.

hierarchy

The UNS enterprise-hierarchy declaration: an ordered, freely-named list of levels whose last level is the physical node (its value is always the resolved thing name). Absent ⇒ the zero-config default ["device"]. Object, strict.

Field	Type	Default	Meaning
levels	array of string (min 1)	["device"]	Ordered level names, deepest (the device) last — e.g. ["site", "factory", "zone", "device"]. Names are strict (^[A-Za-z0-9_-]+$, unique) because they become identity keys (and, later, Parquet columns).

identity

The UNS identity values for every hierarchy level except the last (the last level’s value is always the resolved thing name). Keys must match hierarchy.levels[0..n-2]; a key equal to the last level name — or not a declared level — is a startup error. Values pass through the template sanitizer before use. Object; keys match ^[A-Za-z0-9_-]+$, values are strings.

{
  "hierarchy": { "levels": ["site", "factory", "zone", "device"] },
  "identity":  { "site": "dallas", "factory": "finishing", "zone": "zone-3" }
}

topic

UNS topic-building options. Object, strict.

Field	Type	Default	Meaning
includeRoot	boolean	false	Insert the first hierarchy value (the site) after the ecv1 root in built topics — ecv1/{site}/{device}/... — for multi-site broker deployments. Effective only with a multi-level hierarchy (a no-op + WARN with the single-level default).

component (required)

Your component’s own configuration. Object, strict at this level; the nested global and instances[] payloads are open (arbitrary keys).

Field	Type	Default	Meaning
global	object (open — additionalProperties: true)	—	Config applied to all instances; arbitrary component keys.
instances	array of objects (open; each requires id)	—	Per-instance config for multi-instance components.
instances[].id	string	(required)	Unique instance identifier.

messaging

Dual-MQTT broker configuration: a local broker plus an optional generic northbound MQTT broker. The same shape is used as the standalone messaging-config file passed via --platform HOST --transport MQTT <file>. In GREENGRASS mode, messaging uses IPC and this section is typically absent. Object, strict.

Field	Type	Meaning
local	object (mqttBroker)	The local MQTT broker connection (required when using the MQTT transport).
northbound	object (mqttBroker)	The optional generic northbound MQTT broker connection.
requestTimeoutSeconds	number (min 0), default 30	The default request() deadline: on expiry the reply future completes exceptionally and the ephemeral reply subscription is cleaned up. 0 disables the default; an explicit per-call timeout always wins.

mqttBroker.qos

Default MQTT QoS for operations on that broker that do not take an explicit QoS argument. Configure it under each broker: messaging.local.qos and, when present, messaging.northbound.qos.

MQTT QoS values are:

Value	Meaning
0	At most once. The broker/client sends once and does not acknowledge delivery.
1	At least once. Delivery is acknowledged; duplicates are possible.
2	Exactly once. MQTT’s two-phase handshake avoids duplicate delivery.

Field	Type	Default	Meaning
publish	integer enum 0 | 1 | 2	1	QoS level for publish, publishRaw, request publish, and reply publish on this broker.
subscribe	integer enum 0 | 1 | 2	1	QoS level for subscribe and request reply subscriptions on this broker.

mqttBroker

A single MQTT broker connection. Object, strict.

Field	Type	Default	Allowed values	Meaning
type	string	(none)	—	Broker type tag (e.g. mqtt). Set by the Java/Python samples; ignored by Rust/TS.
host	string	(none)	—	Broker host.
endpoint	string	(none)	—	Broker endpoint FQDN. Equivalent to host for northbound broker configs.
port	integer (1–65535)	(none)	—	Broker port (e.g. 1883 plaintext, 8883 TLS).
clientId	string	(none)	—	MQTT client id.
qos	object (mqttBroker.qos)	{ "publish": 1, "subscribe": 1 }	—	MQTT publish/subscribe QoS defaults for this broker (0 at most once, 1 at least once, 2 exactly once).
credentials	object (mqttCredentials)	—	—	Broker authentication (below).

mqttCredentials

Broker authentication. Object, strict. For local and northbound brokers, TLS is triggered solely by the presence of caPath (useSSL = credentials != null && caPath != null), not by the client certificate fields.

Field	Type	Default	Meaning
username	string	(none)	Username for plaintext MQTT auth.
password	string	(none)	Password for plaintext MQTT auth.
certPath	string	(none)	Client certificate path (TLS / mutual TLS).
keyPath	string	(none)	Client private-key path (TLS / mutual TLS).
caPath	string	(none)	CA bundle path (server-trust / mutual TLS).

TLS trigger rules: TLS is keyed only on caPath. caPath alone ⇒ server-trust TLS (no client cert); caPath + certPath + keyPath ⇒ mutual TLS. A certPath/keyPath supplied without caPath stays plaintext — the client cert is ignored. username/password apply only to plaintext MQTT auth.

streaming

High-rate telemetry streaming to Kinesis or Kafka, fronted by the embedded durable/in-memory buffer. Object, strict.

When this section is inherited from a hierarchical config layer, it is still just configuration. Each component opens and owns its own streams, buffers, drains, metrics, and shutdown lifecycle. For disk buffers, configure paths that resolve per component, commonly with {ComponentName}.

Field	Type	Meaning
streams	array of objects (stream)	The set of named streams to open (below).

stream

A single telemetry stream. Object, strict; requires name and sink.

Field	Type	Default	Meaning
name	string	(required)	Stream identifier.
sink	object (streamSink)	(required)	Export destination (tagged union, below).
buffer	object (streamBuffer)	—	Embedded buffer tuning (below).
batch	object (streamBatch)	—	Export batching tuning (below).
delivery	object (streamDelivery)	—	Retry/polling behavior (below).

stream.sink

A tagged union on type (exactly one variant). Strict.

type: "kinesis" (requires type, streamName):

Field	Type	Default	Allowed values	Meaning
type	string	—	kinesis	Selects the Kinesis sink.
streamName	string	(required)	—	Kinesis data-stream name (template variables).
region	string | null	(none)	—	AWS region.
endpointUrl	string | null	(none)	—	Override endpoint (e.g. LocalStack/floci/VPC).

type: "kafka" (requires type, bootstrapServers, topic):

Field	Type	Default	Allowed values	Meaning
type	string	—	kafka	Selects the Kafka sink.
bootstrapServers	string	(required)	—	Kafka bootstrap servers.
topic	string	(required)	—	Kafka topic.
properties	object (open string→string)	—	—	Extra librdkafka producer properties.

type: "file" (requires type, dir):

Field	Type	Default	Allowed values	Meaning
type	string	—	file	Selects the rolling Parquet/AVRO file sink.
format	string	parquet	parquet, avro	Output encoding (columnar vs row-oriented).
mode	string	rows	rows, raw	rows = typed columns via the rows projection (default = the SouthboundSignalUpdate layout, envelope tags as one JSON column); raw = opaque-payload archival.
dir	string	(required)	—	Output directory root (template variables).
partitionBy	string | null	(none)	—	Hive-style partition sub-path; UTC time tokens {yyyy}/{MM}/{dd}/{HH}/{yyyy-MM-dd}.
maxFileBytes	number (min 0)	134217728 (128 MiB)	—	Roll past this size (soft cap, at row-group granularity).
maxFiles	number (min 0)	0	—	Max finalized files under dir (0 = unbounded).
rollEverySecs	number (min 0)	0	—	Also roll after this many seconds (0 = disabled).
onFull	string	dropOldest	dropOldest, stop	Retention when maxFiles is reached.
compression	string	snappy	none, snappy, zstd, gzip	File compression codec.
rows	object	(none)	—	rows-mode column projection: explode (string, optional) + columns[] (each name, path, type ∈ string/long/double/bool/json). Absent → the built-in SouthboundSignalUpdate default projection.

stream.buffer

Embedded buffer. disk is durable/file-backed (needs path); memory is a non-durable RAM ring. Object, strict.

Field	Type	Default	Allowed values	Meaning
type	string	disk	disk, memory	Buffer backing.
path	string	(none)	—	Buffer directory (disk only).
segmentBytes	number (min 0)	67108864 (64 MiB)	—	Segment file size.
maxDiskBytes	number (min 0)	1073741824 (1 GiB)	—	Maximum on-disk (or in-memory byte) backlog.
maxAgeSecs	number | null (min 0)	(none)	—	Drop records older than this.
onFull	string	dropOldest	dropOldest, block, rejectNew	Behavior when the buffer is full.
fsync	string	perBatch	always, perBatch, interval	Durability flush policy.
fsyncIntervalMs	number (min 0)	1000	—	Flush interval when fsync: interval.
maxBufferedRecords	number (min 0)	10000	—	In-flight record cap.

stream.batch

Export batching tuning. Object, strict.

Field	Type	Default	Allowed values	Meaning
maxRecords	number (min 0)	500	—	Max records per export batch.
maxBytes	number (min 0)	4194304 (4 MiB)	—	Max bytes per export batch.
maxLatencyMs	number (min 0)	1000	—	Max time to wait before flushing a partial batch.
compression	string	none	none, zstd	Batch compression.

stream.delivery

Export retry/polling behavior. Object, strict.

Field	Type	Default	Meaning
maxRetries	number	(none — -1 = retry forever)	Max delivery retries before giving up.
backoffBaseMs	number (min 0)	50	Base backoff between retries.
backoffMaxMs	number (min 0)	30000	Maximum backoff.
pollIntervalMs	number (min 0)	100	Drain poll interval.

credentials

Encrypted local vault, with optional central sync from AWS Secrets Manager. Object, strict.

Field	Type	Meaning
vault	object (credentialsVault)	Local vault settings (below).
central	object (credentialsCentral)	Optional central sync (below).
audit	object (strict)	Access-audit logging — audit.enabled (boolean, default true); never logs secret values.

credentials.vault

Local encrypted vault settings. Object, strict.

Field	Type	Default	Meaning
path	string	vault	Vault directory (template variables).
keyProvider	object (keyProvider)	—	KEK custodian (below).
keepVersions	number (min 0)	2	Number of prior secret versions to retain.
cacheTtlSecs	number (min 0)	300	In-memory decrypt cache TTL.

keyProvider

The envelope-encryption KEK custodian, tagged by type. Used by both credentials.vault.keyProvider and parameters.cache.keyProvider. Fields not used by the selected type are ignored. Object, strict.

Field	Type	Default	Allowed values	Meaning
type	string	file	file, env, kms, greengrass, pkcs11	KEK source. env is the offline software-KEK and the KUBERNETES default.
keyPath	string | null	(none)	—	file: path to the keyfile.
envVar	string | null	(default name EDGECOMMONS_VAULT_KEK)	—	env: env var holding the base64-encoded 32-byte KEK (from a mounted Secret).
kmsKeyId	string | null	(none)	—	kms/greengrass: KMS key id/ARN.
region	string | null	(none)	—	kms/greengrass: AWS region.
endpointUrl	string | null	(none)	—	kms/greengrass: override endpoint.
modulePath	string | null	(none)	—	pkcs11: PKCS#11 module .so/.dll path.
tokenLabel	string | null	(none)	—	pkcs11: token label.
keyLabel	string | null	(none)	—	pkcs11: key label.
pinEnv	string | null	(none)	—	pkcs11: env var holding the PIN (preferred over inline pin).
pin	string | null	(none)	—	pkcs11: inline PIN (discouraged).

credentials.central

Optional central sync. Object, strict.

Field	Type	Default	Allowed values	Meaning
type	string	none	none, awsSecretsManager	none = local-only.
region	string | null	(none)	—	AWS region.
endpointUrl	string | null	(none)	—	Override Secrets Manager endpoint.
refreshIntervalSecs	number (min 0)	300	—	Background refresh interval.
bootstrapOnStart	boolean	true	—	Pull declared secrets at startup.
sync.secrets	array	—	—	Which secrets this device pulls (below).

Each entry in sync.secrets is either a bare string (the central id, a namespaced path) or an object { "name": "...", "from": "..." } where name is the local name and from (string | null) is an explicit or shared central id.

parameters

Offline-first externalized config, reusing the credentials vault as an encrypted cache. Object, strict.

Field	Type	Default	Meaning
source	object (paramSource)	—	Where parameters come from (below).
cache	object (paramCache)	—	Offline-first cache (below).
refreshIntervalSecs	number (min 0)	300	Background refresh interval (0 = no periodic refresh).
bootstrapOnStart	boolean	true	Pull the declared sync names/paths at startup (non-fatal on failure).
sync	object (paramSync)	—	Selective bootstrap/refresh selection (below).

parameters.source

Parameter source, tagged by type. Fields not used by the selected type are ignored. Object, strict.

Field	Type	Default	Allowed values	Meaning
type	string	none (schema default — see note)	env, mountedDir, awsSsm	Source kind. none is not selectable: although the schema declares it the default, the source factory has no none case and throws at startup (ParameterException, “supported: env, mountedDir, awsSsm”). So if you add a parameters section, you must set source.type to one of env / mountedDir / awsSsm.
prefix	string	(none)	—	env: variable-name prefix (e.g. GG_PARAM_).
root	string	(none)	—	mountedDir: root directory of the mounted tree.
securePaths	array of string	(none)	—	mountedDir: path prefixes whose values are sensitive.
region	string | null	(none)	—	awsSsm: AWS region.
endpointUrl	string | null	(none)	—	awsSsm: override SSM endpoint.
withDecryption	boolean	true	—	awsSsm: decrypt SecureString parameters.

parameters.cache

Offline-first cache. Persistence is source-aware by default: remote sources persist encrypted, local sources stay in memory. Object, strict.

Field	Type	Default	Meaning
persist	boolean | null	(none — source-aware)	Override the source-aware persistence default.
path	string	param-cache	Cache directory.
keyProvider	object (keyProvider)	—	KEK custodian for the encrypted cache (see keyProvider).

parameters.sync

Selective bootstrap/refresh — which parameters to pull. Object, strict.

Field	Type	Meaning
names	array of string	Explicit parameter names to sync.
paths	array	Path prefixes to sync; each entry is a bare string (recursive) or { "path": "...", "recursive": true }.

health

Kubernetes HTTP health/readiness endpoint. Exposes GET /livez (process alive; never checks the broker), GET /readyz (200 only when messaging is connected and the component is ready; 503 during startup and shutdown), and an optional GET /startupz. Object, strict.

Field	Type	Default	Allowed values	Meaning
enabled	boolean	(tri-state — see below)	—	Enable the HTTP health server.
port	integer (1–65535)	8081	—	TCP port the server listens on.
livenessPath	string	/livez	—	Liveness route.
readinessPath	string	/readyz	—	Readiness route.
startupPath	string	/startupz	—	Startup route (reuses readiness semantics).

health.enabled has no schema default — it is tri-state. When absent, the platform decides: true on KUBERNETES, false everywhere else. Set it explicitly to force the behavior.

A complete example

A multi-section component config document (this validates clean against the schema):

{
  "logging": { "level": "DEBUG", "rust_format": "{timestamp} [{level}] [{component}] {target} - {message}" },
  "heartbeat": {
    "enabled": true,
    "intervalSecs": 5,
    "measures": { "cpu": true, "memory": true },
    "destination": "local"
  },
  "metricEmission": { "target": "log", "namespace": "edgecommons" },
  "hierarchy": { "levels": ["site", "device"] },
  "identity": { "site": "factory-1" },
  "credentials": {
    "vault": {
      "path": "./.vault/vault",
      "keyProvider": { "type": "file", "keyPath": "./.vault/vault.key" }
    }
  },
  "parameters": {
    "source": { "type": "env", "prefix": "GG_PARAM_" },
    "refreshIntervalSecs": 0,
    "sync": { "names": ["/skeleton/region", "/skeleton/poolSize"] }
  },
  "tags": { "site": "factory-1" },
  "component": {
    "global": { "publish_interval": 3 },
    "instances": [ { "id": "main" } ]
  }
}

The messaging section is most often supplied as a separate file passed via --platform HOST --transport MQTT <file>, rather than embedded in the component config:

{
  "messaging": {
    "local": { "host": "localhost", "port": 1883, "clientId": "ts-skeleton-local" }
  }
}

More committed examples live under examples/{java,python,rust,ts}/test-configs/ and templates/*/test-configs/.

Related pages

Configuration guideConfig sources, template variables, change listeners, and hot reload — with code in all four languages.

Config API referenceThe typed accessors for reading each section from your component code.

Platforms & transportsHow the platform and transport are selected and what each profile defaults to.