Platform Spec

JSON schemas for platform constitutions and app design conventions.

Overview

┌─────────────────────┐      ┌─────────────────┐      ┌─────────────────────┐
│  CONSTITUTION.json  │ ───► │    Renderer     │ ───► │  CONSTITUTION.md    │
│  (Canonical IR)     │      │ (Deterministic) │      │  (Human-Readable)   │
└─────────────────────┘      └─────────────────┘      └─────────────────────┘

Platform Spec provides machine-readable JSON schemas for:

• Constitution - Technology stack, architecture patterns, conformance rules
• App Design - Behavioral conventions for consistent UX across products

Schemas

Schema	Purpose
constitution.schema.json	Tech stack, architecture, conformance rules
app-design.schema.json	UI behaviors, interactions, formatting

Structure

platform-spec/
├── schema/
│   ├── constitution.schema.json
│   └── app-design.schema.json
├── examples/
│   └── plexusone/
│       ├── CONSTITUTION.json
│       └── app-design.json
├── templates/
│   └── CONSTITUTION.md.tmpl
└── README.md

Constitution Schema

Defines platform-level standards:

{
  "$schema": "https://plexusone.dev/platform-spec/v1/constitution.schema.json",
  "meta": { "name": "My Platform", "version": "1.0.0" },
  "principles": [
    { "id": "web-first", "title": "Web First", "description": "..." }
  ],
  "stack": {
    "components": { "framework": "lit", "version": "^3.0.0" },
    "contentSites": { "framework": "astro" },
    "appSites": { "framework": "react" }
  },
  "architecture": {
    "contentSite": {
      "structure": [
        { "path": "src/pages/", "purpose": "File-based routing" }
      ]
    }
  },
  "conformance": {
    "rules": [
      { "id": "no-hardcoded-colors", "severity": "warning", "pattern": "#[0-9a-f]{6}" }
    ]
  }
}

App Design Schema

Defines behavioral conventions:

{
  "$schema": "https://plexusone.dev/platform-spec/v1/app-design.schema.json",
  "layouts": {
    "sidebar": { "width": "280px", "collapsible": true }
  },
  "interactions": {
    "modals": { "backdrop": "blur", "closeOnEscape": true },
    "toasts": { "position": "bottom-right", "duration": 5000 }
  },
  "states": {
    "loading": { "skeleton": true, "minDuration": 300 }
  },
  "formatting": {
    "dates": { "format": "MMMM d, yyyy" }
  }
}

Validation

# Validate constitution
npx ajv validate --spec=draft2020 --strict=false \
  -s schema/constitution.schema.json \
  -d examples/plexusone/CONSTITUTION.json

# Validate app design
npx ajv validate --spec=draft2020 --strict=false \
  -s schema/app-design.schema.json \
  -d examples/plexusone/app-design.json

Relationship to Other Specs

platform-spec (this repo)
├── constitution.schema.json  ─── references ──► design-system-spec
├── app-design.schema.json
│
└── Implementations:
    ├── plexusone/plexusone-platform/CONSTITUTION.json
    ├── productbuildershq/productbuildershq-platform/CONSTITUTION.json
    └── aistandardsio/aistandardsio-platform/CONSTITUTION.json

Integration with VisionSpec

Platform Spec integrates with VisionSpec for:

• CONSTITUTION.md generation from CONSTITUTION.json
• Conformance checking against codebase
• Spec evaluation and reconciliation

# Generate CONSTITUTION.md from JSON
visionspec constitution render

# Check code conformance
visionspec constitution check ./src

License

MIT