Profile Schemas Reference¶

ntkDeploy uses a schema-driven form system to generate the profile editor dynamically. The schema defines every field that appears in the editor, enforces validation rules, and determines the structure of the exported appconfig.json.

Current schema registry version: v1.0

Prerequisites¶

Understand what profiles are — see Glossary.
Familiar with creating profiles — see Creating a Profile.

How the Schema System Works¶

The SchemaRegistry holds one or more versioned SchemaDefinition objects.
Each SchemaDefinition contains a root ObjectField that describes every field in the configuration.
When you open the profile editor, the form is built entirely from this schema — no hard-coded UI.
Before saving or deploying, the settings map is validated against the schema. Any error blocks the operation.
On export, the validated settings are re-encoded as minified JSON. No schemaVersion key is injected into the deployment JSON payload.

Field Types¶

Type	JSON output type	Description
`StringField`	`string`	Single-line text input
`BoolField`	`boolean`	Toggle switch
`IntField`	`number`	Integer input
`EnumField`	`string`	Dropdown — value must be one of the defined options
`ObjectField`	`object`	Collapsible group of nested fields
`ArrayField`	`array`	Repeatable list of objects matching an item schema
`ProviderMapField`	`object`	Map of provider IDs to provider configuration objects
`StringCnfField`	`array of arrays`	CNF attribute list: outer array is AND, inner arrays are OR
`StringArrayField`	`array of strings`	Simple list of strings

Validation Rules by Type¶

Type	Possible validation errors
`StringField`	Required check; `minLength`; `maxLength`; regex `pattern` (custom error via `patternError`)
`BoolField`	Must be a boolean if provided
`IntField`	Required check; `min` bound; `max` bound; must parse as integer
`EnumField`	Required check; value must be in the declared `options` list
`ObjectField`	Required check; must be a `Map`; all child fields validate recursively
`ArrayField`	Required check; must be a `List`; `minItems`; `maxItems`; each item validates against `itemSchema`
`ProviderMapField`	Must be a `Map` if provided
`StringCnfField`	Must be a `List`; each element must be a non-empty `List<String>` (OR groups must be non-empty)
`StringArrayField`	Must be a `List<String>`; `minItems`; `maxItems`

Schema v1.0 — Top-Level Sections¶

The root schema for appconfig.json contains these top-level sections:

Section key	Label	Required
`fileProcessing`	File Processing	No
`metadataBackup`	Metadata Backup	No
`syncSettings`	Sync Settings	No
`mainProvider`	Main Provider	Yes
`cloudProviders`	Cloud Providers	No
`sources`	Source Folders	No
`deviceId`	Device ID	Yes
`conductorAddress`	Conductor Address	Yes
`policy`	Policy Bundle	No

Section: File Processing (`fileProcessing`)¶

Field key	Label	Type	Required	Default	Notes
`encryptFile.enabled`	Enable File Encryption	Bool	No	`true`	Encrypts files before upload
`compressedFile.enabled`	Enable Compression	Bool	No	`true`	Compresses files before upload
`redundantShred.enabled`	Enable Redundant Shred	Bool	No	`false`	Enables IDA sharding
`redundantShred.threshold`	Threshold	Int	No	`2`	Min shards for recovery (1–10)
`redundantShred.shredCount`	Shred Count	Int	No	`4`	Total shards created (2–20)
`redundantShred.distribution.roundRobin`	Round Robin	Bool	No	`true`
`redundantShred.distribution.redundant`	Redundant	Bool	No	`false`
`redundantShred.distribution.random`	Random	Bool	No	`false`
`redundantShred.recoveryOptions.useEncryptedFile`	Use Encrypted File	Bool	No	`true`
`redundantShred.recoveryOptions.idaOnly`	IDA Only	Bool	No	`false`
`fipsMode`	FIPS Mode	Bool	No	`false`	FIPS-compliant crypto
`zeroTrustStorage`	Zero Trust Storage	Bool	No	`false`
`dehydrateHoldSeconds`	Dehydrate Hold (seconds)	Int	No	`30`	Range 0–3600
`redundantStorage`	Redundant Storage	Bool	No	`false`	Store redundantly across providers

Section: Metadata Backup (`metadataBackup`)¶

Field key	Label	Type	Required	Default
`uploadEncryptedDBBackup`	Upload Encrypted DB Backup	Bool	No	`false`
`backupDBToThumbDrive.enabled`	Enable USB Backup	Bool	No	`false`
`backupDBToThumbDrive.location`	Backup Location	String	No	`""`

Section: Sync Settings (`syncSettings`)¶

Field key	Label	Type	Required	Default	Range
`syncFileDeletions`	Sync File Deletions	Bool	No	`false`	—
`externalCheckMaxConcurrency`	External Check Concurrency	Int	No	`0`	0–100
`networkConnectTimeoutMs`	Connect Timeout (ms)	Int	No	`10000`	1000–60000
`networkRequestTimeoutMs`	Request Timeout (ms)	Int	No	`15000`	1000–120000

Section: Main Provider (`mainProvider`)¶

Required. Selects the primary cloud storage provider for the profile.

Value	Label
`MinIO`	MinIO
`AmazonS3`	Amazon S3
`NetworkShare`	Network Share
`Wasabi`	Wasabi
`iDriveE2`	iDrive E2
`OneDrive`	OneDrive
`DropBox`	Dropbox
`GoogleDrive`	Google Drive

Default: MinIO.

Section: Cloud Providers (`cloudProviders`)¶

Contains one configuration entry per provider type. The cloudProviders object is keyed by provider ID. Each provider entry has the following container structure:

Container key	Type	Description
`enabled`	Boolean	Whether this provider type is active for the profile
`config`	Array of objects	One object per configured provider instance

Example structure:

{
  "cloudProviders": {
    "MinIO": {
      "enabled": true,
      "config": [ { "displayName": "My MinIO", "endpointOverride": "...", ... } ]
    }
  }
}

Each object in config[] contains the provider-specific fields listed below. OAuth providers (OneDrive, DropBox, GoogleDrive) do not support multiple instances (config[] holds at most one entry).

Common Fields (all credential providers)¶

Key	Label	Required
`displayName`	Display Name	Yes
`providerInstanceId`	Instance ID	Yes

Key	Label	Required	Notes
`location`	UNC Path	Yes	e.g., `\\server\share\path`

Amazon S3 / Wasabi / iDrive E2¶

Key	Label	Required	Default
`accessKey`	Access Key	Yes	—
`secretKey`	Secret Key	Yes	—
`bucketName`	Bucket Name	Yes	—
`buckets`	Additional Buckets	No	Semicolon-separated
`endpointOverride`	Endpoint Override	No	Leave empty for AWS default
`region`	Region	No	`us-east-1`

MinIO¶

Same fields as Amazon S3, but endpointOverride (MinIO server URL) is required.

OneDrive / Dropbox / Google Drive (OAuth)¶

OAuth providers do not support multiple instances. Only displayName is configurable.

Section: Source Folders (`sources`)¶

An array of source folder definitions. Each item has the following fields:

Key	Label	Type	Required	Notes
`folderPath`	Folder Path	String	Yes	Local path to sync
`associatedProvider`	Associated Provider	Enum	Yes	Same options as `mainProvider`
`fileProcessingOverride`	File Processing Override	Object	No	Per-source override of global file processing settings (see nested fields below)
`syncSettingsOverride`	Sync Settings Override	Object	No	Per-source override of global sync settings (see nested fields below)
`abacAttributes`	ABAC Attributes	StringCnfField	No	CNF format: `[["tag1","tag2"],["tag3"]]`
`providerAssignments`	Provider Assignments	Array	No	List of provider instance assignments

Nested Fields: `fileProcessingOverride`¶

All fields mirror the global fileProcessing section and are optional. Only defined keys override the global value.

Field key	Label	Type	Default
`encryptFile.enabled`	Enable File Encryption	Bool	inherits global
`compressedFile.enabled`	Enable Compression	Bool	inherits global
`redundantShred.enabled`	Enable Redundant Shred	Bool	inherits global
`redundantShred.threshold`	Threshold	Int	inherits global
`redundantShred.shredCount`	Shred Count	Int	inherits global
`redundantShred.distribution.roundRobin`	Round Robin	Bool	inherits global
`redundantShred.distribution.redundant`	Redundant	Bool	inherits global
`redundantShred.distribution.random`	Random	Bool	inherits global
`redundantShred.recoveryOptions.useEncryptedFile`	Use Encrypted File	Bool	inherits global
`redundantShred.recoveryOptions.idaOnly`	IDA Only	Bool	inherits global
`fipsMode`	FIPS Mode	Bool	inherits global
`zeroTrustStorage`	Zero Trust Storage	Bool	inherits global
`dehydrateHoldSeconds`	Dehydrate Hold (seconds)	Int	inherits global
`redundantStorage`	Redundant Storage	Bool	inherits global

Note: When fileProcessingOverride.encryptFile.enabled is true, abacAttributes on this source entry must be non-empty (see cross-field validation below).

Nested Fields: `syncSettingsOverride`¶

All fields mirror the global syncSettings section and are optional.

Field key	Label	Type	Default
`syncFileDeletions`	Sync File Deletions	Bool	inherits global
`externalCheckMaxConcurrency`	External Check Concurrency	Int	inherits global
`networkConnectTimeoutMs`	Connect Timeout (ms)	Int	inherits global
`networkRequestTimeoutMs`	Request Timeout (ms)	Int	inherits global

Cross-field Validation Rules¶

Rule	Error message
Encryption enabled in `fileProcessingOverride` → `abacAttributes` must be non-empty	`ABAC attributes are required when file encryption is enabled`
`providerAssignments` entry uses a bucket-capable provider (S3, MinIO, Wasabi, iDrive E2) → `assignedBucket` must be set	`Assigned Bucket is required for provider assignment type <providerId>`

Provider Assignment Item¶

Key	Required
`providerInstanceId`	Yes
`providerId`	Yes
`assignedBucket`	Conditional — required for S3-family providers

Section: Device Settings¶

Key	Label	Type	Required	Default
`deviceId`	Device ID	String	Yes	`device-agent-001`
`conductorAddress`	Conductor Address	String	Yes	`xdrive.dev:9010`

Section: Policy Bundle (`policy`)¶

Optional top-level field. Contains embedded policy data fetched from the policy server at deployment time.

Key	Label	Notes
`policy.serverMetadata.baseUrl`	Base URL	Policy server endpoint
`policy.serverMetadata.fetchedAt`	Fetched At	ISO 8601 timestamp
`policy.selectedPolicyIds`	Selected Policy IDs	String array
`policy.attributeDefinitions`	Attribute Definitions	Array of `{id, displayName, description}`
`policy.assignments`	Policy Assignments	Array of `{attributeKey, attributeValues[], expiry}`

Validation Summary¶

The schema validator runs recursively. Errors are aggregated and returned as a list of human-readable strings. Deployment is blocked if any error is present.

Validation is triggered: - On manual Validate action (Ctrl+Enter in the profile editor). - Automatically before saving a profile version. - During the deployment pipeline when building the JSON payload for each target device.

Next Steps¶

Creating a Profile — use the schema-driven editor.
Importing and Exporting — understand conflict handling during import.
Deployment Preflight Reference — see how schema validation fits into the deployment pipeline.