← Referencejui.config.jsonThe keys the toolchain reads from jui.config.json that a project most often sets, in one place: core directories, platform roots, build normalization, API model generation, test install targets, doc contract checks, and lint bounds. Until now these were scattered across the pages that use them.hand-maintained
The file and how it is foundjui.config.json lives at the project root and is the single project-level configuration for the whole toolchain — jui, the platform builders it drives, jsonui-test and jsonui-doc all resolve it. Commands look for it in the current directory and upward; MCP tools take an explicit project_dir (or the JUI_PROJECT_DIR environment variable) instead. `jui init` writes the initial file. One project can hold several of these. When specs sit in one subtree and the config that owns them in another, put a stub on the specs' own ancestry naming its owner — `{ "extends": "../../web/jui.config.json" }` — and the run resolves the API documents and the naming convention from that one file rather than from whichever partial config happens to be nearest (see Referencing the API canon from a spec).
Core directoriesThe top-level string keys point the toolchain at your spec, layout, style, image, component-spec and swagger directories. The values below are the built-in defaults — a key you omit falls back to exactly these. strings_file has no default: localization is off until you point it at a strings.json. document_tools_path is only needed when jsonui-doc is not importable from the standard install.⚠️ document_tools_path changes where the tools come from, which the sentence above does not say. Point it at a directory that exists and `document_tools` resolves to that working copy instead of the installed distribution — so `jui --version` no longer describes what is running, and an edit in that copy silently becomes the toolchain. Point it at a directory that does not exist and the setting does nothing at all: the import falls back to the installed CLI. Each case prints a NOTE on stderr naming which of the two happened.The notice is not printed by every command. `jui build` reports the broken case, because a path that does not exist is a fact about the setting and is true no matter what runs — but it stays silent when the path exists, because it never prepends it. A command that did not do the work does not report having done it.
jui.config.json — core keys and their defaults
{ "project_name": "my-app", "spec_directory": "docs/screens/json", "layouts_directory": "docs/screens/layouts", "styles_directory": "docs/screens/styles", "images_directory": "docs/screens/images", "component_spec_directory": "docs/components/json", "strings_file": "docs/screens/layouts/Resources/strings.json", "type_map_file": ".jsonui-type-map.json", "api_directory": "docs/api", "platforms": { }}platforms.*One block per shipped platform. `root` is the platform project directory; `layoutsDir` / `imagesDir` are where `jui build` distributes layouts and images inside that root. iOS additionally takes `xcassetsDir`, Android `drawableDir`. A platform without a block simply is not built. `jui build` first checks that each platform's `layoutsDir` is where that platform's own tool reads its layouts (sjui.config.json and kjui.config.json: source_directory + layouts_directory; rjui.config.json: layouts_directory), with the Styles beside it, and stops before distributing anything when they disagree, naming the value to set. Measured with `layoutsDir` "src/views" and an rjui.config.json reading src/layouts: [web] jui build writes the layouts to web/src/views (jui.config.json platforms.web.layoutsDir "src/views"), but rjui.config.json reads web/src/layouts (source_directory + layouts_directory): set platforms.web.layoutsDir to "src/layouts", exit 1; "./src/layouts/" is the same folder and passes. The comparison goes by the spelling, so src/Layouts is stopped against src/layouts even on a disk that ignores case. `jui init` writes each platform's `layoutsDir` from its tool's config. The web block below is this documentation site's real configuration.What `jui build` writes from docs/screens/images. Web copies each SVG as it is into `imagesDir`. iOS writes an imageset into `xcassetsDir` holding a PDF. iOS puts the PNG or JPEG itself in the imageset instead of a PDF, when all four hold: the SVG has no shapes and exactly one <image>; its href is a data:image/png or data:image/jpeg URI; it sits at 0,0 and fills the canvas; its pixels are 1, 2 or 3 times the viewBox (one pixel of slack). At 2 or 3 times the imageset says scale 2x or 3x, so the picture keeps the SVG's size in points. Any other SVG is a PDF: an image moved off 0,0, a shape beside it, two images, a WebP, and 1.5 times the viewBox each stayed a PDF here. Android writes a vector drawable into `drawableDir` for an SVG of shapes alone. An SVG with a picture keeps it: one embedded PNG, JPEG or WebP filling the canvas goes as it is to drawable-nodpi/<name>.<ext> beside `drawableDir`, and any other SVG with an <image> (shapes over a picture, two pictures, a picture that does not fill the canvas) is drawn as a PNG at three times its size in drawable-xxhdpi/<name>.png, so it keeps its size in dp. jsonui-cli says that without rsvg-convert or cairosvg no PNG is drawn and a WARNING is printed; that was not run here. An <image> whose href is a URL prints a WARNING on iOS, Android and web, because no platform fetches it and the picture is blank; what is written does not change.
When an SVG changes between those forms, `jui build` removes the earlier form's file only if jui wrote it. On iOS that is a file the set's previous Contents.json names, when its author is jui: a file the Contents.json does not name stays, and overwriting a Contents.json whose author is not jui (one Xcode made) leaves the files it named and prints a WARNING. On Android jui records what it wrote in .jsonui-cli/image-outputs.json at the project root, and the first build, with no record, removes nothing. A file of the same name that jui did not write stays beside jui's output, and `jui build` names it and removes nothing. In the folder jui wrote to (drawable/logo.png beside jui's drawable/logo.xml, or drawable-nodpi/logo.jpg beside its drawable-nodpi/logo.png) it prints an ERROR line, because Android's own build stops on two files of one resource name in one folder; the build goes on and still writes iOS and web, then exits 1 (0 only with --allow-partial). In another folder it prints a WARNING saying which file a device shows: drawable-nodpi/logo.png beside jui's drawable/logo.xml is shown at 240 dpi and above, and drawable/logo.xml beside jui's drawable-nodpi/logo.png at 160 dpi and below. A file in one density folder (drawable-hdpi) also gets a WARNING, saying the device's configuration decides; your own set across two density folders (drawable-mdpi and drawable-hdpi) is yours and gets nothing, and neither does a file of another name. Measured by calling the shipped converter the way jui build does, on scratch SVGs and planted files; the exit status was read from the build's stage ledger, not from a full Android build, and which file a device shows, like Android's build stopping on a same-folder pair, is jsonui-cli's measurement. No app was compiled, and this site builds web only, so none of this runs here.
platforms.* — per-platform roots and distribution dirs
"platforms": { "ios": { "root": "ios-app", "layoutsDir": "Layouts", "imagesDir": "Images", "xcassetsDir": "Assets.xcassets" }, "android": { "root": "android-app", "layoutsDir": "app/src/main/assets/Layouts", "drawableDir": "app/src/main/res/drawable" }, "web": { "root": "jsonui-doc-web", "layoutsDir": "src/Layouts", "imagesDir": "public/images" }}build.normalizeLayoutsDefault true: `jui build` distributes L1-canonicalized layouts (aliases rewritten to canonical names) and stamps the $jui marker on each distributed file. Set false for byte-identical-to-legacy distribution — the escape hatch, not the recommendation.
build.normalizeLayouts — default true; false is the escape hatch
"build": { "normalizeLayouts": false}verifyTwo switches decide what `jui verify --fail-on-diff` counts besides drift. `external`: a screen whose layout is authored outside the spec (metadata.layoutFile with no structure.components) is held to its spec — every name the layout binds and every entry of its data section must be declared in what goes into the data section (uiVariables, and what displayLogic, a collection and a tab view generate; a name only in dataFlow.viewModel's vars or methods, or in eventHandlers, is reported as such). "warn" (the default) reports the findings; "gate" also fails --fail-on-diff on them, and on a layout that could not be checked. Any other value is an error. `requireSpecPerScreen`: true makes a screen layout with no spec, or a spec naming a layout that does not exist, fail --fail-on-diff; by default they are listed only. This site sets external to gate.
verify — both default to reported only
"verify": { "external": "gate", "requireSpecPerScreen": true}api.*Drives the API models `jui build` writes (swagger → DTO + Domain models) and `jui g api --dry-run` previews. `api.platforms.<p>` sets the output locations per platform — the values below are the built-in defaults (Android's serializer accepts moshi / kotlinx / none, web's case_convention accepts snake_case / camelCase). `api.schemas` is the endpoint/schema filter: include/exclude path globs pick endpoints, include/exclude schema globs adjust the schema set, and skip_domain names schemas that emit DTOs only. format_mapping opts into OpenAPI format-driven type mapping, with format_mapping_exclude as its per-format opt-out list. `api.enum_unknown_case` (default true) gives the generated iOS and Android enums a case for a value the app does not know; false turns it off on both (/concepts/data-models-from-openapi). `api.platforms.ios.modules` writes the schemas it names into a Swift module of their own, public by default, for a framework the app shares with an App Extension (/concepts/data-models-from-openapi).
api.* — model generation targets + swagger filter
"api": { "platforms": { "ios": { "model_dir": "Model", "dto_subdir": "Generated" }, "android": { "model_package": "model", "dto_subpackage": "generated", "serializer": "moshi" }, "web": { "model_dir": "models", "dto_subdir": "generated", "case_convention": "snake_case" } }, "schemas": { "include_paths": ["/api/v1/**"], "exclude_paths": ["/api/v1/internal/**"], "include_schemas": ["Shared*"], "exclude_schemas": [], "skip_domain": ["*Meta"] }, "format_mapping": false, "format_mapping_exclude": []}test.*`test.appOwnedScreens` names screens the app implements by hand — a splash or a legal page with no JsonUI layout behind it — so `jui screens` classifies them correctly. They are ids, not layouts, which is also why the spec-coverage check leaves them alone: it looks for layouts with no spec. `test.install` gives jsonui-test its copy targets: when present, a passing `jsonui-test validate` also installs the validated test JSON into each platform's test bundle (iOS additionally takes uitestBundleId for the pre-grant step; a platform value can be a plain path string). `test.appOwnedIds` declares element ids the app draws outside every layout — a native navigation bar's menu item, an app toast — so `jsonui-test validate` does not report them as ids on no layout; an entry ending in `*` is a prefix, and a declaration no step of the run names is listed so a stale one can be removed. It is for elements the app really draws, not for silencing a misspelled id: the validator names the layout ids a person may have meant.
test.* — screen identity + generated-test install targets
"test": { "appOwnedScreens": ["Splash"], "appOwnedIds": ["appToast", "nav_menu_*"], "install": { "ios": { "target_dir": "ios-app/UITests/GeneratedTests", "uitestBundleId": "com.example.AppUITests.xctrunner" }, "android": { "assets_dir": "android-app/app/src/androidTest/assets/tests" }, "web": { "dir": "web/e2e/tests" } }}checks[] + databases{}Declarations for `jsonui-doc check` — the doc-contract checker. Each entry has a name, a type (builtin:db-schema, builtin:openapi-diff, builtin:infra-iac, builtin:infra-code, or checker for a custom script) and an optional timeout_seconds (default 60). db-schema entries reference a database from databases{} (each declares its dialect) and may pin a dump_command plus ignore_tables; openapi-diff entries must declare impl_openapi_command and may narrow with ignore_paths / ignore_response_codes / scope (all | generated). They may also set per-comparison-key severity: ignore_schema_keys drops the comparison entirely, downgrade_to_warning keeps the finding with its expected/actual detail but takes it off the gate. Both take names from a closed set — type, nullable, enum, required, format, format_presence — so a typo is a config error rather than a silently ineffective filter, and listing the same key in both is an error too (a dropped comparison cannot be reported). The two format keys stand in an umbrella relation: format_presence covers only annotation differences, where one side declares a format and the other says nothing (docs pinning uuid against a plain string, or an impl declaring email) — the type, the wire value and the generated DTO all agree, so this is docs being deliberately stricter rather than drift. Plain format covers that plus the contradictions, where both sides declare a format and the values disagree (date-time against uuid), which is a genuine type drift. The useful setting is downgrade_to_warning: ["format_presence"], which silences the annotation noise while leaving real format contradictions on the gate. The types builtin:infra-iac and builtin:infra-code compare the infrastructure model with the project's IaC and with its code; they take ignore_types (IaC resource types not compared) and gate (false by default, so findings are warnings). builtin:infra-load compares the model with the cost simulator's load definitions and takes gate the same way. The model's folder is the top-level infra.dir (default docs/infra, a relative path inside the project), and infra.load_dir and infra.prices_dir move the load definitions and the price files (default <infra.dir>/load and <infra.dir>/prices); and infra.icons maps service:<provider>/<service>, provider:<p> or category:<c> to an SVG, PNG or WebP inside the project; infra.exclude lists folders inside the project that seed and the infra-iac / infra-code checks do not walk into. Credentials never go in this file — connection info comes from environment variables, and declared commands must resolve inside the project.
checks[] + databases{} — jsonui-doc check declarations
"databases": { "main": { "dialect": "postgresql" }},"checks": [ { "name": "db-main", "type": "builtin:db-schema", "database": "main", "dump_command": "python scripts/dump_schema.py", "ignore_tables": ["schema_migrations"] }, { "name": "api-diff", "type": "builtin:openapi-diff", "impl_openapi_command": "python -m app.export_openapi", "scope": "generated", "timeout_seconds": 120 }]lint.*Bounds for `jui lint-generated`. lint.max_depth and lint.max_lines can only tighten below the generator's own cut points (depth 5 / 250 lines) — a looser value is clamped with a warning, so the config can never mask what the generators enforce. exclude_dir_names and exclude_files take extra paths out of the scan (extensions/ trees, vendored files). Two keys belong to `jui lint-strings` instead: `lint.stringsUsage: true` runs its usage check on every run (the same as `--usage`), and `lint.stringsUsageTestPaths` names, per platform, more directories of test code — references from test code do not count as usage.
lint.* — jui lint-generated bounds (tighten-only)
"lint": { "max_depth": 4, "max_lines": 200, "exclude_dir_names": ["extensions"], "exclude_files": []}Keep reading
CLI command referenceThe commands that read every key on this page./reference/cli-commands
DB schema checkWhat checks[] declarations actually verify./concepts/db-schema-check