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 underlying appconfig JSON body shown in previews and used during build.

Current schema registry version: v1.0

Deployment Envelope Notes¶

This page describes the JSON bodies produced by the schema system. For desktop deployment, ntkDeploy does not write unencrypted appconfig.json to disk anymore. It encrypts the built desktop JSON body into appconfig.ntkd using the same NtkProfileCrypto envelope as mobile .ntkprofile files.

Parameter	Value
Format version	`0x02`
KDF	`PBKDF2WithHmacSHA256`
Iterations	`210000`
Salt	16 bytes
IV	12 bytes
Cipher	AES-256-GCM
Auth tag	128 bits
Password verifier prefix	`ntk-mobile-profile-v2`
Envelope size limit	256 KiB

Desktop deployed output strips the top-level policy object entirely. When ABAC preflight resolves a client identity, deviceId remains the sole client-side identity reference in the deployed payload before encryption.

Mobile Settings Schema¶

Profiles targeting Mobile or Both also carry a separate mobile settings document under mobileSettings. This mobile document is independent from the desktop appconfig JSON body described below.

The mobile settings structure is centered on:

conductorAddress
vaults[]

Each mobile vault can include:

name
provider
description
encryptionType (boolean toggle in the editor, labeled Encryption — new vaults default to true, which maps to "Enabled" in the built payload; false maps to "Disabled")
providerAssignments (array of provider instance references — connection details are resolved at build time)
settings

Note: ABAC attributes for mobile vaults are configured on the Policy tab, not inside the vault form. They are stored in the profile's policy data alongside desktop source ABAC.

Unlike the desktop schema, the mobile schema is not derived from desktop sources. The profile editor validates mobileSettings directly and the mobile builder reads saved vault data directly when producing .ntkprofile output.

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 ABAC ID list: outer array is AND, inner arrays are OR. IDs stay string-only; imported TPA factors persist as canonical lowercase 32-hex `tpaId` values alongside internal attribute IDs
`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 the preview/build-time appconfig JSON body 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)
`providerAssignments`	Provider Assignments	Array	No	List of provider instance assignments

Note: ABAC attributes for desktop sources are configured on the Policy tab, not in the source item form. Saved ABAC values remain string-only IDs: internal attributes use their existing IDs, and imported TPA factors use canonical lowercase 32-hex tpaId values.

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: ABAC for desktop sources is configured on the Policy tab, not as a source form field. The source editor still participates in policy and preflight flows through the saved profile data. Those saved ABAC values remain string-only IDs across both internal and imported-TPA factors.

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

deviceId is part of the schema and preview/build-time JSON body. During final desktop deployment, the policy bundle is stripped entirely. The top-level deviceId remains in the deployed payload only when the ABAC/snapshot path stamps it during build; when ABAC data is present, that top-level deviceId is the sole client-side identity reference.

Section: Policy Bundle (`policy`)¶

Optional top-level field. Contains embedded policy data fetched from the policy server at deployment time for build-time review and audit context.

Key	Label	Notes
`policy.serverMetadata.baseUrl`	Policy Manager 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}`

The final encrypted desktop payload written to appconfig.ntkd removes the entire policy object before deployment. deviceId is the only client-side identity field retained when ABAC applies.

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.

Mobile Profile Schema v1¶

Mobile profiles use a separate schema from the desktop appconfig JSON body. The mobile schema defines the structure of the encrypted payload written to .ntkprofile files. It is validated by MobileProfileValidator before encryption is applied.

The schema contract lives at docs/ntkMobile/profile-schema-v1.json.

Top-level fields¶

Field	Type	Required	Notes
`profileId`	String (UUID)	Yes	Stable identifier. Generated on first build; never regenerated for the same profile.
`profileName`	String	Yes	Max 200 characters. Copied from the ntkDeploy profile display name.
`schemaVersion`	Integer	Yes	Always `1`.
`conductorAddress`	String	No	`host:port` format. Injected from Settings → Conductor Address if configured; omitted otherwise.
`vaults`	Array of vault objects	Yes	1–50 entries. Each entry is an independent mobile vault definition authored in the Mobile Vaults editor.

Vault object fields¶

Field	Type	Required	Notes
`name`	String	Yes	Max 100 characters. Copied from the vault display name.
`provider`	Enum	Yes	One of: `S3`, `S3_COMPATIBLE`, `ONEDRIVE`, `DROPBOX`, `GDRIVE`.
`encryptionType`	String	No	`"Enabled"` or `"Disabled"`. New vaults default to `"Enabled"`. Derived from the vault's Encryption toggle set in the Mobile Vaults editor.
`providerConfig`	Object	Yes	Provider-specific connection configuration resolved from the assigned provider instance at build time. For S3-family providers includes `endpoint`, `region`, `bucket`, `accessKey`, and `secretKey`. An optional `providerExtras` sub-object carries additional flags such as `forcePathStyle` and `teamDriveId`.
`settings`	Object	No	Per-vault sync and behaviour settings (see below). Omitted when all settings resolve to null.
`abacAttributes`	Array of string arrays	No	CNF format — same structure as desktop `sources[].abacAttributes`. Each string is an ABAC ID: either an internal attribute ID or an imported cross-org TPA `tpaId`. Imported TPA IDs are persisted as canonical lowercase 32-hex strings. Configured via the Policy tab and embedded at build time. Omitted when no ABAC attributes are configured.

Vault `settings` object¶

The settings object maps desktop profile fields to their mobile equivalents:

Mobile key	Source field	Type	Notes
`compressOnUpload`	`fileProcessing.compressedFile.enabled`	Boolean	Omitted when the source setting is not configured.
`syncDeletions`	`syncSettings.syncFileDeletions`	Boolean	Omitted when the source setting is not configured.
`zeroTrustEnabled`	`fileProcessing.zeroTrustStorage`	Boolean	Omitted when the source setting is not configured.
`strictMode`	`fileProcessing.fipsMode`	Boolean	Derived from the desktop FIPS Mode setting. Omitted when not configured.

Constraints¶

Constraint	Value
Vault count	1–50
Vault name length	≤ 100 characters
Profile name length	≤ 200 characters
Conductor address format	`host:port`, port 1–65535
Maximum envelope size	256 KiB

Validation¶

MobileProfileValidator runs all constraints above before the payload is passed to NtkProfileCrypto. A validation failure aborts the build and records a mobile_profile_build_failed audit event. The payload is never encrypted if validation fails. Desktop appconfig.ntkd uses the same envelope format after its JSON body is built.

Next Steps¶

Creating a Profile — use the schema-driven editor.
Importing and Exporting — understand conflict handling during import.
Mobile Profiles — generate encrypted .ntkprofile files for ntkMobile.
Deployment Preflight Reference — see how schema validation fits into the deployment pipeline.