openuispec 0.1.0

package/schema/defs/common.schema.json

@@ -0,0 +1,330 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/defs/common.schema.json",
+  "title": "OpenUISpec Common Definitions",
+  "description": "Shared type definitions used across OpenUISpec schemas",
+  "$defs": {
+    "icon_ref": {
+      "type": "string",
+      "description": "Reference to a named icon from the icon registry (e.g. 'checkmark_circle', 'folder_fill'). Resolved against icons.yaml registry with platform-specific mappings at generation time."
+    },
+    "color_ref": {
+      "type": "string",
+      "description": "Color reference \u2014 hex value (#RRGGBB) or token path (color.brand.primary)"
+    },
+    "token_ref": {
+      "type": "string",
+      "description": "Reference to a design token (e.g. 'spacing.md', 'typography.body')"
+    },
+    "media_ref": {
+      "type": "string",
+      "description": "Reference to a media asset or data path for images/avatars"
+    },
+    "screen_ref": {
+      "type": "string",
+      "description": "Reference to a screen (e.g. 'screens/home', 'screens/task_detail')"
+    },
+    "severity": {
+      "type": "string",
+      "enum": [
+        "info",
+        "success",
+        "warning",
+        "error",
+        "neutral"
+      ],
+      "description": "Severity level for badges, feedback, and status indicators"
+    },
+    "size_class": {
+      "type": "string",
+      "enum": [
+        "compact",
+        "regular",
+        "expanded"
+      ],
+      "description": "Responsive size class breakpoint"
+    },
+    "contract_family": {
+      "type": "string",
+      "enum": [
+        "action_trigger",
+        "data_display",
+        "input_field",
+        "nav_container",
+        "feedback",
+        "surface",
+        "collection"
+      ],
+      "description": "One of the 7 component contract families"
+    },
+    "contract_ref": {
+      "type": "string",
+      "description": "Built-in contract family or custom contract (x_ prefixed)"
+    },
+    "platform_target": {
+      "type": "string",
+      "enum": [
+        "ios",
+        "android",
+        "web"
+      ],
+      "description": "Target platform identifier"
+    },
+    "locale_ref": {
+      "type": "string",
+      "pattern": "^\\$t:",
+      "description": "Internationalization reference string (e.g. '$t:home.greeting')"
+    },
+    "string_or_locale": {
+      "description": "A plain string or a $t: locale reference",
+      "type": "string"
+    },
+    "badge_config": {
+      "type": "object",
+      "description": "Badge configuration for navigation items and indicators",
+      "properties": {
+        "text": {
+          "type": "string"
+        },
+        "count": {
+          "type": [
+            "string",
+            "integer"
+          ]
+        },
+        "dot": {
+          "type": "boolean"
+        },
+        "severity": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "range_object": {
+      "type": "object",
+      "description": "A base value with a constrained range",
+      "properties": {
+        "base": {
+          "type": "number"
+        },
+        "range": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          },
+          "minItems": 2,
+          "maxItems": 2
+        }
+      },
+      "required": [
+        "base",
+        "range"
+      ],
+      "additionalProperties": false
+    },
+    "size_value": {
+      "description": "Either a fixed number or a base+range object",
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/range_object"
+        }
+      ]
+    },
+    "hsl_range": {
+      "type": "object",
+      "description": "HSL color range constraints",
+      "properties": {
+        "hue": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "saturation": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "lightness": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          },
+          "minItems": 2,
+          "maxItems": 2
+        }
+      },
+      "additionalProperties": false
+    },
+    "on_color": {
+      "type": "object",
+      "description": "Foreground color for use on top of a background color",
+      "properties": {
+        "reference": {
+          "type": "string"
+        },
+        "contrast_min": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "reference"
+      ],
+      "additionalProperties": false
+    },
+    "icon_object": {
+      "type": "object",
+      "description": "Inline icon specification with optional styling",
+      "properties": {
+        "ref": {
+          "type": "string"
+        },
+        "icon": {
+          "type": "string"
+        },
+        "position": {
+          "type": "string",
+          "enum": [
+            "leading",
+            "trailing"
+          ]
+        },
+        "color": {
+          "type": "string"
+        },
+        "size": {
+          "type": "number"
+        },
+        "background": {
+          "type": "string"
+        },
+        "radius": {
+          "type": [
+            "string",
+            "number"
+          ]
+        },
+        "padding": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "leading_trailing": {
+      "description": "Leading or trailing content \u2014 can be an icon object, a media object, a nested contract, or a string",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/icon_object"
+        },
+        {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/media_object"
+        },
+        {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/nested_contract"
+        }
+      ]
+    },
+    "media_object": {
+      "type": "object",
+      "description": "Media content with fallback",
+      "properties": {
+        "media": {
+          "type": "string"
+        },
+        "fallback": {
+          "type": "object",
+          "properties": {
+            "initials": {
+              "type": "string"
+            },
+            "background": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        "size": {
+          "type": "number"
+        },
+        "radius": {
+          "type": [
+            "string",
+            "number"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "nested_contract": {
+      "type": "object",
+      "description": "An inline contract instance used in props (leading/trailing/content)",
+      "properties": {
+        "contract": {
+          "$ref": "https://openuispec.org/schema/defs/common.schema.json#/$defs/contract_ref"
+        },
+        "variant": {
+          "type": "string"
+        },
+        "input_type": {
+          "type": "string"
+        },
+        "props": {
+          "type": "object"
+        },
+        "action": {
+          "$ref": "https://openuispec.org/schema/defs/action.schema.json"
+        },
+        "data_binding": {
+          "type": "string"
+        },
+        "tokens_override": {
+          "type": "object"
+        },
+        "adaptive": {
+          "$ref": "https://openuispec.org/schema/defs/adaptive.schema.json"
+        },
+        "behavior": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "contract",
+        "props"
+      ],
+      "additionalProperties": true
+    },
+    "tokens_override": {
+      "type": "object",
+      "description": "Token override map \u2014 keys are token names, values are token references or literal values",
+      "additionalProperties": true
+    },
+    "empty_state": {
+      "type": "object",
+      "description": "Empty state configuration for collections",
+      "properties": {
+        "icon": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "body": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/defs/data-binding.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/defs/data-binding.schema.json",
+  "title": "OpenUISpec Data Binding Definitions",
+  "description": "Data sources, state definitions, data paths, and format expressions",
+  "$defs": {
+    "data_source": {
+      "type": "object",
+      "description": "A data source definition with API endpoint and optional params",
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "API endpoint or data provider reference"
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "refresh": {
+          "type": "object",
+          "properties": {
+            "interval": {
+              "type": "integer"
+            },
+            "on_focus": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": true
+        },
+        "cache": {
+          "type": "object",
+          "properties": {
+            "ttl": {
+              "type": "integer"
+            },
+            "strategy": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "source"
+      ],
+      "additionalProperties": true
+    },
+    "state_def": {
+      "type": "object",
+      "description": "Screen-level state variable definition",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "State variable type (enum, string, bool, int, etc.)"
+        },
+        "values": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Allowed values for enum types"
+        },
+        "default": {
+          "description": "Default value for this state variable"
+        }
+      },
+      "required": [
+        "type",
+        "default"
+      ],
+      "additionalProperties": false
+    },
+    "data_map": {
+      "type": "object",
+      "description": "Map of named data sources",
+      "additionalProperties": {
+        "$ref": "https://openuispec.org/schema/defs/data-binding.schema.json#/$defs/data_source"
+      }
+    },
+    "state_map": {
+      "type": "object",
+      "description": "Map of named state definitions",
+      "additionalProperties": {
+        "$ref": "https://openuispec.org/schema/defs/data-binding.schema.json#/$defs/state_def"
+      }
+    },
+    "params_map": {
+      "type": "object",
+      "description": "Map of screen/flow parameter definitions",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string"
+          },
+          "required": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "t_params": {
+      "type": "object",
+      "description": "Translation parameter bindings \u2014 keys are param names, values are data paths",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean"
+        ]
+      }
+    }
+  }
+}

package/schema/defs/validation.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.org/schema/defs/validation.schema.json",
+  "title": "OpenUISpec Validation",
+  "description": "Validation rule definitions for input_field contracts (Section 13)",
+
+  "$defs": {
+    "string_or_locale": {
+      "type": "string",
+      "description": "Plain text message or $t: locale reference"
+    },
+
+    "validate_trigger": {
+      "type": "string",
+      "enum": ["on_blur", "on_change", "on_submit"],
+      "description": "When to run validation: on_blur (default), on_change (every keystroke), on_submit (only on form submission)"
+    },
+
+    "validation_rules": {
+      "type": "object",
+      "description": "Co-located validation rules for an input_field instance",
+      "properties": {
+        "pattern": {
+          "type": "object",
+          "description": "Regex pattern validation",
+          "properties": {
+            "regex": { "type": "string" },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["regex"],
+          "additionalProperties": false
+        },
+        "min_length": {
+          "type": "object",
+          "description": "Minimum string length",
+          "properties": {
+            "value": { "type": "integer", "minimum": 0 },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["value"],
+          "additionalProperties": false
+        },
+        "max_length": {
+          "type": "object",
+          "description": "Maximum string length",
+          "properties": {
+            "value": { "type": "integer", "minimum": 0 },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["value"],
+          "additionalProperties": false
+        },
+        "min": {
+          "type": "object",
+          "description": "Minimum numeric value",
+          "properties": {
+            "value": { "type": "number" },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["value"],
+          "additionalProperties": false
+        },
+        "max": {
+          "type": "object",
+          "description": "Maximum numeric value",
+          "properties": {
+            "value": { "type": "number" },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["value"],
+          "additionalProperties": false
+        },
+        "format": {
+          "type": "object",
+          "description": "Built-in format validation",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["email", "url", "phone", "uuid"]
+            },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["type"],
+          "additionalProperties": false
+        },
+        "match_field": {
+          "type": "object",
+          "description": "Cross-field equality check (e.g., password confirmation)",
+          "properties": {
+            "field": { "type": "string", "description": "data_binding path of the field to match" },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["field"],
+          "additionalProperties": false
+        },
+        "custom": {
+          "type": "object",
+          "description": "Custom expression-based validation",
+          "properties": {
+            "expression": { "type": "string", "description": "Condition expression using the same grammar as condition (Section 5)" },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["expression"],
+          "additionalProperties": false
+        },
+        "async": {
+          "type": "object",
+          "description": "Server-side async validation (e.g., username availability)",
+          "properties": {
+            "endpoint": { "type": "string", "description": "API endpoint reference (same format as api_call)" },
+            "debounce": { "type": "integer", "minimum": 0, "description": "Debounce in milliseconds (default: 300)" },
+            "message": { "$ref": "#/$defs/string_or_locale" }
+          },
+          "required": ["endpoint"],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}