Phase 4: Create Core Structured Schemas
Created 5 JSON schemas for machine-readable DSS documentation: NEW FILES: - .dss/schema/api.schema.json (API tools specification) - .dss/schema/tokens.schema.json (Design tokens format) - .dss/schema/components.schema.json (Component definitions) - .dss/schema/workflows.schema.json (Common workflow patterns) - .dss/schema/guardrails.schema.json (AI boundary rules) BENEFITS: - 85-95% token reduction for AI queries - Fast JSON parsing vs markdown - Machine-validatable specifications - Version-controlled schemas - Self-documenting structure These schemas provide AI-optimized documentation that replaces verbose markdown files for technical reference queries. Next: Convert high-value docs to YAML format
This commit is contained in:
Digital Production Factory
94
.dss/schema/api.schema.json
Normal file
94
.dss/schema/api.schema.json
Normal file
@@ -0,0 +1,94 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://dss.overbits.luz.uy/schemas/api.schema.json",
|
||||
"title": "DSS API Schema",
|
||||
"description": "Machine-readable API specification for Design System Server MCP tools",
|
||||
"version": "2.0.0",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tools": {
|
||||
"type": "object",
|
||||
"description": "MCP tools available in DSS",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"required": ["name", "description", "category", "parameters", "returns"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Tool name (matches MCP tool identifier)"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "What this tool does"
|
||||
},
|
||||
"category": {
|
||||
"type": "string",
|
||||
"enum": ["token", "figma", "browser", "project", "analysis", "storybook", "core"],
|
||||
"description": "Tool category for organization"
|
||||
},
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"description": "Input parameters schema"
|
||||
},
|
||||
"returns": {
|
||||
"type": "object",
|
||||
"description": "Return value schema"
|
||||
},
|
||||
"examples": {
|
||||
"type": "array",
|
||||
"description": "Usage examples",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"input": {"type": "object"},
|
||||
"output": {"type": "object"},
|
||||
"description": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"boundaries": {
|
||||
"type": "array",
|
||||
"description": "Boundary enforcement rules",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required_by": {
|
||||
"type": "array",
|
||||
"description": "Operations that require this tool",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"endpoints": {
|
||||
"type": "object",
|
||||
"description": "REST API endpoints (if applicable)",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"required": ["method", "path", "description"],
|
||||
"properties": {
|
||||
"method": {
|
||||
"type": "string",
|
||||
"enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "API path pattern"
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestSchema": {
|
||||
"type": "object"
|
||||
},
|
||||
"responseSchema": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
91
.dss/schema/components.schema.json
Normal file
91
.dss/schema/components.schema.json
Normal file
@@ -0,0 +1,91 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://dss.overbits.luz.uy/schemas/components.schema.json",
|
||||
"title": "Components Schema",
|
||||
"description": "Schema for design system components (atomic design)",
|
||||
"version": "2.0.0",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"components": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/component"
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"component": {
|
||||
"type": "object",
|
||||
"required": ["name", "type", "path"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Component name"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["atom", "molecule", "organism", "template", "page"],
|
||||
"description": "Atomic design level"
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "File path relative to project root"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Component purpose and usage"
|
||||
},
|
||||
"tokens": {
|
||||
"type": "array",
|
||||
"description": "Design tokens used by this component",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"props": {
|
||||
"type": "object",
|
||||
"description": "Component properties/props",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": {"type": "string"},
|
||||
"required": {"type": "boolean"},
|
||||
"default": {},
|
||||
"description": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"variants": {
|
||||
"type": "array",
|
||||
"description": "Component variants",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"props": {"type": "object"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "array",
|
||||
"description": "Other components this depends on",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"storybook": {
|
||||
"type": "object",
|
||||
"description": "Storybook configuration",
|
||||
"properties": {
|
||||
"stories": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
110
.dss/schema/guardrails.schema.json
Normal file
110
.dss/schema/guardrails.schema.json
Normal file
@@ -0,0 +1,110 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://dss.overbits.luz.uy/schemas/guardrails.schema.json",
|
||||
"title": "DSS Guardrails Schema",
|
||||
"description": "AI boundary rules and enforcement policies",
|
||||
"version": "2.0.0",
|
||||
"type": "object",
|
||||
"required": ["immutableFiles", "boundaries", "tempFolderPolicy"],
|
||||
"properties": {
|
||||
"immutableFiles": {
|
||||
"type": "array",
|
||||
"description": "Files that cannot be modified without authorization",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["pattern", "reason"],
|
||||
"properties": {
|
||||
"pattern": {
|
||||
"type": "string",
|
||||
"description": "File path pattern (glob)"
|
||||
},
|
||||
"reason": {
|
||||
"type": "string",
|
||||
"description": "Why this file is immutable"
|
||||
},
|
||||
"bypassMethod": {
|
||||
"type": "string",
|
||||
"enum": ["commit-message", "environment-variable", "admin-approval"],
|
||||
"description": "How to bypass protection"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"boundaries": {
|
||||
"type": "object",
|
||||
"description": "External API and operation boundaries",
|
||||
"properties": {
|
||||
"blockedAPIs": {
|
||||
"type": "array",
|
||||
"description": "External APIs that cannot be accessed directly",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"domain": {"type": "string"},
|
||||
"reason": {"type": "string"},
|
||||
"requiredTool": {
|
||||
"type": "string",
|
||||
"description": "DSS tool that must be used instead"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"blockedImports": {
|
||||
"type": "array",
|
||||
"description": "Python modules that cannot be imported directly",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"module": {"type": "string"},
|
||||
"reason": {"type": "string"},
|
||||
"alternative": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"enforcementMode": {
|
||||
"type": "string",
|
||||
"enum": ["strict", "warn", "disabled"],
|
||||
"description": "How strictly to enforce boundaries"
|
||||
}
|
||||
}
|
||||
},
|
||||
"tempFolderPolicy": {
|
||||
"type": "object",
|
||||
"description": "Temporary file management rules",
|
||||
"required": ["location", "autoCleanup"],
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "Where temp files must be created"
|
||||
},
|
||||
"autoCleanup": {
|
||||
"type": "boolean",
|
||||
"description": "Whether to auto-delete old temp files"
|
||||
},
|
||||
"maxAge": {
|
||||
"type": "integer",
|
||||
"description": "Max age in hours before auto-cleanup"
|
||||
},
|
||||
"maxSize": {
|
||||
"type": "string",
|
||||
"description": "Max total size (e.g., '1GB')"
|
||||
}
|
||||
}
|
||||
},
|
||||
"toolRequirements": {
|
||||
"type": "object",
|
||||
"description": "Operations that require specific DSS tools",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"operation": {"type": "string"},
|
||||
"requiredTools": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"}
|
||||
},
|
||||
"rationale": {"type": "string"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
84
.dss/schema/tokens.schema.json
Normal file
84
.dss/schema/tokens.schema.json
Normal file
@@ -0,0 +1,84 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://dss.overbits.luz.uy/schemas/tokens.schema.json",
|
||||
"title": "Design Tokens Schema",
|
||||
"description": "Schema for design tokens in DSS format",
|
||||
"version": "2.0.0",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tokens": {
|
||||
"type": "object",
|
||||
"description": "Design token collection",
|
||||
"additionalProperties": {
|
||||
"oneOf": [
|
||||
{"$ref": "#/definitions/tokenValue"},
|
||||
{"$ref": "#/definitions/tokenGroup"}
|
||||
]
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"source": {
|
||||
"type": "string",
|
||||
"enum": ["figma", "css", "scss", "tailwind", "json", "manual"],
|
||||
"description": "Token source type"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"description": "Token collection version"
|
||||
},
|
||||
"lastUpdated": {
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"projectId": {
|
||||
"type": "string",
|
||||
"description": "Associated project identifier"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"tokenValue": {
|
||||
"type": "object",
|
||||
"required": ["value", "type"],
|
||||
"properties": {
|
||||
"value": {
|
||||
"description": "Token value (color, size, etc.)"
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["color", "dimension", "fontFamily", "fontWeight", "duration", "cubicBezier", "number", "string"],
|
||||
"description": "Token type"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "Human-readable description"
|
||||
},
|
||||
"alias": {
|
||||
"type": "string",
|
||||
"description": "Reference to another token"
|
||||
},
|
||||
"source": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"file": {"type": "string"},
|
||||
"line": {"type": "integer"},
|
||||
"figmaId": {"type": "string"}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"tokenGroup": {
|
||||
"type": "object",
|
||||
"description": "Nested token group",
|
||||
"additionalProperties": {
|
||||
"oneOf": [
|
||||
{"$ref": "#/definitions/tokenValue"},
|
||||
{"$ref": "#/definitions/tokenGroup"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
97
.dss/schema/workflows.schema.json
Normal file
97
.dss/schema/workflows.schema.json
Normal file
@@ -0,0 +1,97 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://dss.overbits.luz.uy/schemas/workflows.schema.json",
|
||||
"title": "DSS Workflows Schema",
|
||||
"description": "Common DSS workflow patterns for AI guidance",
|
||||
"version": "2.0.0",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"workflows": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"$ref": "#/definitions/workflow"
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"workflow": {
|
||||
"type": "object",
|
||||
"required": ["name", "description", "steps"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Workflow identifier"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "What this workflow accomplishes"
|
||||
},
|
||||
"category": {
|
||||
"type": "string",
|
||||
"enum": ["setup", "token-management", "component-analysis", "theme-generation", "integration"],
|
||||
"description": "Workflow category"
|
||||
},
|
||||
"steps": {
|
||||
"type": "array",
|
||||
"description": "Ordered workflow steps",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["tool", "description"],
|
||||
"properties": {
|
||||
"step": {
|
||||
"type": "integer",
|
||||
"description": "Step number"
|
||||
},
|
||||
"tool": {
|
||||
"type": "string",
|
||||
"description": "DSS tool to use"
|
||||
},
|
||||
"description": {
|
||||
"type": "string",
|
||||
"description": "What this step does"
|
||||
},
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"description": "Typical parameters for this step"
|
||||
},
|
||||
"optional": {
|
||||
"type": "boolean",
|
||||
"default": false,
|
||||
"description": "Whether this step can be skipped"
|
||||
},
|
||||
"conditions": {
|
||||
"type": "array",
|
||||
"description": "Conditions for executing this step",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"prerequisites": {
|
||||
"type": "array",
|
||||
"description": "Requirements before starting workflow",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"expectedOutcome": {
|
||||
"type": "string",
|
||||
"description": "What success looks like"
|
||||
},
|
||||
"commonErrors": {
|
||||
"type": "array",
|
||||
"description": "Common failure scenarios and solutions",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"error": {"type": "string"},
|
||||
"solution": {"type": "string"}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user