206 lines
4.4 KiB
Markdown
206 lines
4.4 KiB
Markdown
# Schema Reference
|
|
|
|
Pointer to the definitive uxscii component schema and how to use it.
|
|
|
|
## The Schema File
|
|
|
|
**Location**: `../schema/uxm-component.schema.json`
|
|
|
|
This is the **definitive source of truth** for the uxscii `.uxm` file format.
|
|
|
|
## What the Schema Defines
|
|
|
|
The schema specifies:
|
|
- All valid field names and types
|
|
- Required vs optional fields
|
|
- Validation rules (min/max, patterns, enums)
|
|
- Nested object structures
|
|
- Field descriptions
|
|
|
|
## How to Use the Schema
|
|
|
|
### For Reference
|
|
|
|
When creating components, refer to the schema to understand:
|
|
- What fields are available
|
|
- What values are allowed
|
|
- What's required vs optional
|
|
|
|
### For Autocompletion
|
|
|
|
Many editors can use the schema for:
|
|
- Field suggestions
|
|
- Type checking
|
|
- Documentation on hover
|
|
|
|
Add to your `.uxm` file:
|
|
```json
|
|
{
|
|
"$schema": "../data/schema/uxm-component.schema.json",
|
|
...
|
|
}
|
|
```
|
|
|
|
## Key Schema Sections
|
|
|
|
### Required Root Fields
|
|
|
|
```
|
|
id - Component identifier (kebab-case, 2-64 chars)
|
|
type - Component type (enum or "custom")
|
|
version - Semantic version (X.Y.Z)
|
|
metadata - Component metadata object
|
|
props - Component properties object
|
|
ascii - ASCII template reference
|
|
```
|
|
|
|
### Metadata Object (required fields)
|
|
|
|
```
|
|
name - Human-readable name (1-100 chars)
|
|
created - ISO 8601 timestamp
|
|
modified - ISO 8601 timestamp
|
|
```
|
|
|
|
### Metadata Object (optional fields)
|
|
|
|
```
|
|
description - Component description (max 500 chars)
|
|
author - Creator name (max 100 chars)
|
|
tags - Array of search tags (max 10)
|
|
category - Component category (enum)
|
|
```
|
|
|
|
### ASCII Object (required)
|
|
|
|
```
|
|
templateFile - Template filename (must end in .md)
|
|
width - Character width (1-120)
|
|
height - Character height (1-50)
|
|
```
|
|
|
|
### ASCII Object (optional)
|
|
|
|
```
|
|
variables - Array of template variable definitions
|
|
```
|
|
|
|
### Behavior Object (optional)
|
|
|
|
```
|
|
states - Array of component states
|
|
interactions - Array of user interactions
|
|
animations - Array of animation definitions
|
|
accessibility- Accessibility attributes
|
|
```
|
|
|
|
## Component Types (Enum)
|
|
|
|
Valid `type` values:
|
|
```
|
|
button, input, card, navigation, form, list, modal,
|
|
table, badge, alert, container, text, image, divider, custom
|
|
```
|
|
|
|
## Categories (Enum)
|
|
|
|
Valid `metadata.category` values:
|
|
```
|
|
layout, input, display, navigation, feedback,
|
|
utility, overlay, custom
|
|
```
|
|
|
|
## Variable Types (Enum)
|
|
|
|
Valid `ascii.variables[].type` values:
|
|
```
|
|
string, number, boolean, color, size, array, object
|
|
```
|
|
|
|
## Quick Reference Examples
|
|
|
|
### Minimal Valid Component
|
|
|
|
```json
|
|
{
|
|
"id": "simple",
|
|
"type": "button",
|
|
"version": "1.0.0",
|
|
"metadata": {
|
|
"name": "Simple",
|
|
"created": "2024-01-01T00:00:00Z",
|
|
"modified": "2024-01-01T00:00:00Z"
|
|
},
|
|
"props": {},
|
|
"ascii": {
|
|
"templateFile": "simple.md",
|
|
"width": 10,
|
|
"height": 3
|
|
}
|
|
}
|
|
```
|
|
|
|
### Complete Component
|
|
|
|
See `../examples/primary-button.uxm` for a fully-featured example using all available fields.
|
|
|
|
## Schema Version
|
|
|
|
Current schema version: **1.1.0**
|
|
|
|
Schema follows semantic versioning:
|
|
- Major: Breaking changes to structure
|
|
- Minor: New optional fields
|
|
- Patch: Documentation or validation updates
|
|
|
|
## Validation Rules Summary
|
|
|
|
### ID Rules
|
|
- Pattern: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
|
|
- Length: 2-64 characters
|
|
- Format: kebab-case only
|
|
|
|
### Version Rules
|
|
- Pattern: `^\d+\.\d+\.\d+(?:-[a-zA-Z0-9-]+)?$`
|
|
- Examples: `1.0.0`, `2.1.3`, `1.0.0-beta`
|
|
|
|
### Timestamp Rules
|
|
- Format: ISO 8601 date-time
|
|
- Example: `2024-10-11T12:00:00Z`
|
|
|
|
### Variable Name Rules
|
|
- Pattern: `^[a-zA-Z][a-zA-Z0-9_]*$`
|
|
- Format: camelCase recommended
|
|
- Examples: `text`, `userName`, `isDisabled`
|
|
|
|
## Common Schema Errors
|
|
|
|
**"Additional property not allowed"**
|
|
- You used a field name that doesn't exist in the schema
|
|
- Check field spelling and location in object hierarchy
|
|
|
|
**"Missing required property"**
|
|
- You omitted a required field
|
|
- Add the field with a valid value
|
|
|
|
**"Value does not match pattern"**
|
|
- Field value doesn't match regex pattern
|
|
- Check format requirements (kebab-case, semver, etc.)
|
|
|
|
**"Value not in enum"**
|
|
- You used a value not in the allowed list
|
|
- Use one of the valid enum values
|
|
|
|
## Deep Dive
|
|
|
|
For comprehensive schema documentation, see:
|
|
- **Full guide**: `UXSCII_SCHEMA_GUIDE.md` (detailed explanations)
|
|
- **Agent guide**: `UXSCII_AGENT_GUIDE.md` (practical examples)
|
|
|
|
## Next Steps
|
|
|
|
- **View schema**: Open `../schema/uxm-component.schema.json`
|
|
- **See examples**: Browse `../examples/*.uxm`
|
|
|
|
The schema ensures all uxscii components are compatible and machine-readable!
|