openuispec 0.1.10 → 0.1.11

package/README.md

@@ -119,6 +119,42 @@ openuispec/
 └── README.md
 ```
 
+## File formats and schemas
+
+Every file type has a corresponding JSON Schema in `schema/`. **Read the schema before creating or editing a file** — do not guess the structure.
+
+| File | Schema | Root key | Example |
+|------|--------|----------|---------|
+| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` | [openuispec.yaml](./examples/taskflow/openuispec.yaml) |
+| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` | [home.yaml](./examples/taskflow/screens/home.yaml) |
+| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` | [create_task.yaml](./examples/taskflow/flows/create_task.yaml) |
+| `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](./examples/taskflow/platform/ios.yaml) |
+| `locales/*.json` | `locale.schema.json` | (object) | [en.json](./examples/taskflow/locales/en.json) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `contract` | [x_media_player.yaml](./examples/taskflow/contracts/x_media_player.yaml) |
+| `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](./examples/taskflow/tokens/color.yaml) |
+| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](./examples/taskflow/tokens/typography.yaml) |
+| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](./examples/taskflow/tokens/spacing.yaml) |
+| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` | [elevation.yaml](./examples/taskflow/tokens/elevation.yaml) |
+| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` | [motion.yaml](./examples/taskflow/tokens/motion.yaml) |
+| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` | [layout.yaml](./examples/taskflow/tokens/layout.yaml) |
+| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` | [themes.yaml](./examples/taskflow/tokens/themes.yaml) |
+| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` | [icons.yaml](./examples/taskflow/tokens/icons.yaml) |
+
+Every token file **must** have a single root wrapper key matching its type:
+
+```yaml
+# Correct — tokens/color.yaml
+color:
+  brand:
+    primary: ...
+
+# Wrong — missing root key
+brand:
+  primary: ...
+```
+
+Validate with: `openuispec validate`
+
 ## Spec at a glance
 
 | Section | What it defines |

package/cli/init.ts

@@ -198,38 +198,30 @@ scale: ...
 
 Root keys: \`color\`, \`typography\`, \`spacing\`, \`elevation\`, \`motion\`, \`layout\`, \`themes\`, \`icons\`.
 
-## JSON Schemas (validation & file structure)
-
-**IMPORTANT:** Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Schemas are located in the installed package:
-
-\`\`\`
-node_modules/openuispec/schema/
-├── openuispec.schema.json        ← root manifest (openuispec.yaml)
-├── screen.schema.json            ← screen files (screens/*.yaml)
-├── flow.schema.json              ← flow files (flows/*.yaml)
-├── platform.schema.json          ← platform overrides (platform/*.yaml)
-├── locale.schema.json            ← locale files (locales/*.json)
-├── custom-contract.schema.json   ← custom contracts (contracts/*.yaml)
-├── tokens/
-│   ├── color.schema.json         ← tokens/color.yaml
-│   ├── typography.schema.json    ← tokens/typography.yaml
-│   ├── spacing.schema.json       ← tokens/spacing.yaml
-│   ├── elevation.schema.json     ← tokens/elevation.yaml
-│   ├── motion.schema.json        ← tokens/motion.yaml
-│   ├── layout.schema.json        ← tokens/layout.yaml
-│   ├── themes.schema.json        ← tokens/themes.yaml
-│   └── icons.schema.json         ← tokens/icons.yaml
-└── defs/
-    ├── common.schema.json        ← shared types (icons, badges, etc.)
-    ├── action.schema.json        ← 13 action types (discriminated union)
-    ├── data-binding.schema.json  ← data sources, state, params
-    ├── adaptive.schema.json      ← adaptive override pattern
-    └── validation.schema.json    ← validation rule definitions
-\`\`\`
-
-**Workflow:** read the schema → create the YAML file → run \`openuispec validate\` to verify.
-
-**Example spec files:** \`node_modules/openuispec/examples/taskflow/\` — a complete app demonstrating all file types. Read these for real-world examples of screens, flows, tokens, and platform overrides.
+## File formats and schemas
+
+**IMPORTANT:** Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Do not guess the file format.
+
+| File | Schema | Root key |
+|------|--------|----------|
+| \`openuispec.yaml\` | \`openuispec.schema.json\` | \`spec_version\` |
+| \`screens/*.yaml\` | \`screen.schema.json\` | \`<screen_id>\` |
+| \`flows/*.yaml\` | \`flow.schema.json\` | \`<flow_id>\` |
+| \`platform/*.yaml\` | \`platform.schema.json\` | \`platform\` |
+| \`locales/*.json\` | \`locale.schema.json\` | (object) |
+| \`contracts/x_*.yaml\` | \`custom-contract.schema.json\` | \`contract\` |
+| \`tokens/color.yaml\` | \`tokens/color.schema.json\` | \`color\` |
+| \`tokens/typography.yaml\` | \`tokens/typography.schema.json\` | \`typography\` |
+| \`tokens/spacing.yaml\` | \`tokens/spacing.schema.json\` | \`spacing\` |
+| \`tokens/elevation.yaml\` | \`tokens/elevation.schema.json\` | \`elevation\` |
+| \`tokens/motion.yaml\` | \`tokens/motion.schema.json\` | \`motion\` |
+| \`tokens/layout.yaml\` | \`tokens/layout.schema.json\` | \`layout\` |
+| \`tokens/themes.yaml\` | \`tokens/themes.schema.json\` | \`themes\` |
+| \`tokens/icons.yaml\` | \`tokens/icons.schema.json\` | \`icons\` |
+
+All schemas are in \`node_modules/openuispec/schema/\`. Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
+
+**Workflow:** read the schema → read an example from \`node_modules/openuispec/examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
 
 ## Spec format quick reference
 
@@ -337,18 +329,29 @@ Every token file must have a single root key matching the token type. Do NOT put
 - \`tokens/themes.yaml\` → root key: \`themes\`
 - \`tokens/icons.yaml\` → root key: \`icons\`
 
-## JSON Schemas — read before creating spec files
-Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure:
-- \`node_modules/openuispec/schema/openuispec.schema.json\` — root manifest
-- \`node_modules/openuispec/schema/screen.schema.json\` — screens
-- \`node_modules/openuispec/schema/flow.schema.json\` — flows
-- \`node_modules/openuispec/schema/platform.schema.json\` — platform overrides
-- \`node_modules/openuispec/schema/locale.schema.json\` — locales
-- \`node_modules/openuispec/schema/custom-contract.schema.json\` — custom contracts
-- \`node_modules/openuispec/schema/tokens/*.schema.json\` — token files (color, typography, spacing, elevation, motion, layout, themes, icons)
-- \`node_modules/openuispec/schema/defs/*.schema.json\` — shared types (actions, data-binding, adaptive, validation, common)
-
-Workflow: read the spec → read the schema → read an example → create the YAML → run \`openuispec validate\`.
+## File formats and schemas — read before creating spec files
+Before creating or editing any spec file, read the corresponding JSON Schema. Do not guess the file format.
+
+| File | Schema (in \`node_modules/openuispec/schema/\`) | Root key |
+|------|--------|----------|
+| \`openuispec.yaml\` | \`openuispec.schema.json\` | \`spec_version\` |
+| \`screens/*.yaml\` | \`screen.schema.json\` | \`<screen_id>\` |
+| \`flows/*.yaml\` | \`flow.schema.json\` | \`<flow_id>\` |
+| \`platform/*.yaml\` | \`platform.schema.json\` | \`platform\` |
+| \`locales/*.json\` | \`locale.schema.json\` | (object) |
+| \`contracts/x_*.yaml\` | \`custom-contract.schema.json\` | \`contract\` |
+| \`tokens/color.yaml\` | \`tokens/color.schema.json\` | \`color\` |
+| \`tokens/typography.yaml\` | \`tokens/typography.schema.json\` | \`typography\` |
+| \`tokens/spacing.yaml\` | \`tokens/spacing.schema.json\` | \`spacing\` |
+| \`tokens/elevation.yaml\` | \`tokens/elevation.schema.json\` | \`elevation\` |
+| \`tokens/motion.yaml\` | \`tokens/motion.schema.json\` | \`motion\` |
+| \`tokens/layout.yaml\` | \`tokens/layout.schema.json\` | \`layout\` |
+| \`tokens/themes.yaml\` | \`tokens/themes.schema.json\` | \`themes\` |
+| \`tokens/icons.yaml\` | \`tokens/icons.schema.json\` | \`icons\` |
+
+Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
+
+Workflow: read the schema → read an example from \`node_modules/openuispec/examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
 
 ## Spec format reference
 - 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/schema/validate.ts

@@ -71,6 +71,8 @@ function buildAjv(): AjvInstance {
   return ajv;
 }
 
+const BASE = "https://openuispec.org/schema/";
+
 // ── validate one file ────────────────────────────────────────────────
 
 function validateFile(
@@ -94,6 +96,12 @@ function validateFile(
     return 0;
   }
 
+  // Convert schema URL to a local path for display
+  const schemaLocalPath = schemaId.replace(
+    BASE,
+    "node_modules/openuispec/schema/",
+  );
+
   const errors: ErrorObject[] = validate.errors ?? [];
   console.log(`  FAIL  ${name} (${errors.length} error(s))`);
   for (const e of errors.slice(0, 5)) {
@@ -109,13 +117,39 @@ function validateFile(
   if (errors.length > 5) {
     console.log(`        ... and ${errors.length - 5} more`);
   }
+
+  // Show hint when root-level structure is wrong (missing wrapper key)
+  const hasRootRequired = errors.some(
+    (e) => !e.instancePath && e.keyword === "required",
+  );
+  const hasRootAdditional = errors.some(
+    (e) => !e.instancePath && e.keyword === "additionalProperties",
+  );
+  if (hasRootRequired || hasRootAdditional) {
+    const expectedKey = errors.find(
+      (e) => !e.instancePath && e.keyword === "required",
+    )?.params?.missingProperty as string | undefined;
+    if (expectedKey) {
+      console.log(
+        `\n        Hint: "${name}" needs a root "${expectedKey}:" wrapper key.`,
+      );
+      console.log(`        Example:`);
+      console.log(`          ${expectedKey}:`);
+      console.log(`            ...your content here...`);
+    } else {
+      console.log(
+        `\n        Hint: This file has unexpected top-level properties.`,
+      );
+    }
+  }
+
+  console.log(`        Schema: ${schemaLocalPath}`);
+
   return errors.length;
 }
 
 // ── validation groups ────────────────────────────────────────────────
 
-const BASE = "https://openuispec.org/schema/";
-
 interface ValidationGroup {
   label: string;
   run(ajv: AjvInstance, projectDir: string): number;