Runic Forms

Custom Schema per Domain

Problem

Hand-written configuration profiles fail quietly: a key is misspelled, a boolean is a string, an array is a dictionary. The tool ignores the value and the admin only finds out when a Mac behaves wrongly. A long admin guide alone does not prevent this.

Context & forces

• Jamf Pro (Applications & Custom Settings → External Applications → Custom Schema) renders forms from a JSON schema. Other MDMs offer similar features or accept plists.
• Some settings are deeply nested (per-vendor settings, workflows) and do not map to simple form fields.
• The schema must stay in sync with what the tool actually reads.
• One tool may read several domains (settings, fragments, workflows), each with its own shape.

Solution

For every domain the tool reads, ship a schema next to the example profiles: titles, descriptions, defaults, enums and types for every key. Deeply nested content gets a textarea field that takes JSON (for example HarnessesJSON); the tool accepts both the native structure and the JSON string. The admin guide names, for each domain, which schema to paste.

 Tool repo: Profiles/ or Jamf/
   <app>-settings-schema.json   ──▶ Jamf custom schema for <app>
   <app>-policy-schema.json     ──▶ Jamf custom schema for <app>.policy.<name>
   example .mobileconfig        ──▶ other MDMs

For developers

• One schema per domain shape. Fragment domains with a variable suffix share one schema.
• Descriptions say what a value does, which values exist, and what happens when it is missing. They are often the only documentation an admin reads.
• Lenient parsing on the device side: accept <true/> and "true", a number or a numeric string, an array or a comma-separated string. Admins and forms produce all of them.
• JSON-in-a-string fields are parsed with clear errors and validated by the tool's own validate command before deployment.
• Keep schema, example profiles and the admin guide's key tables in sync. A test that compares the schema with the keys the code reads catches drift.

Consequences

• Fewer broken deployments and faster setup for admins.
• The schema doubles as a machine-readable reference.
• Free-form JSON fields lose form validation, so the tool must validate them.
• One more artifact to maintain with every new setting.

Known uses

• Gimle ships gimle-jamf-schema.json for com.spectrechen.gimle, including managed instances and policy switches.
• Mimir ships one schema for daemon settings and one for policy fragments, whose harness settings are entered as JSON.
• Ratatoskr ships one schema for the main domain and one for workflow domains.

Name

Runes were the forms in which knowledge was carved so others could read it correctly. The schema carves a tool's settings into a form admins can fill in.