init

schema.md

@@ -0,0 +1,224 @@
+# Schema
+
+The ABC Schema is the authoritative, machine‑readable definition of the ABC
+Pattern. It formalizes:
+
+* Construct types
+* Hierarchy rules
+* Contract requirements
+* Data‑flow semantics
+* Instantiation constraints
+* Validation rules
+* Profile extension hooks
+
+The schema is expressed as a single JSON Schema document, making it suitable
+for:
+
+* Linting
+* Static analysis
+* Code generation
+* Agent reasoning
+* Architecture validation
+* Profile extension (CDKTS, Terraform, Pulumi, etc.)
+
+This schema is intentionally strict. It defines the shape of an ABC
+architecture, not the cloud resources themselves. Profiles map this schema to
+concrete IaC implementations.
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.tiararodney.com/abc/abc.schema.json",
+  "title": "ABC Schema",
+  "description": "The canonical machine-readable schema for the ABC Pattern.",
+  "type": "object",
+
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Schema version identifier."
+    },
+
+    "constructs": {
+      "type": "array",
+      "description": "List of constructs in the ABC architecture.",
+      "items": { "$ref": "#/$defs/Construct" }
+    }
+  },
+
+  "required": ["version", "constructs"],
+
+  "$defs": {
+
+    "Construct": {
+      "type": "object",
+      "description": "A construct in the ABC hierarchy.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the construct."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["ApplicationStack", "LogicalUnit", "ResourceGroup"],
+          "description": "Construct type (ABC-C1, C2, or C3)."
+        },
+        "parent": {
+          "type": ["string", "null"],
+          "description": "Parent construct ID. Null only for ApplicationStack."
+        },
+        "inputs": {
+          "$ref": "#/$defs/InputContract"
+        },
+        "outputs": {
+          "$ref": "#/$defs/OutputContract"
+        },
+        "children": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "IDs of child constructs."
+        }
+      },
+      "required": ["id", "type", "inputs", "outputs", "children"],
+      "allOf": [
+        { "$ref": "#/$defs/HierarchyRules" },
+        { "$ref": "#/$defs/ContractRules" },
+        { "$ref": "#/$defs/DataFlowRules" }
+      ]
+    },
+
+    "InputContract": {
+      "type": "object",
+      "description": "ABC-C4 Input Contract.",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean", "object", "array", "null"]
+      }
+    },
+
+    "OutputContract": {
+      "type": "object",
+      "description": "ABC-C5 Output Contract.",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean", "object", "array", "null"]
+      }
+    },
+
+    "HierarchyRules": {
+      "type": "object",
+      "description": "Hierarchy validation rules.",
+      "properties": {},
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "ApplicationStack" } } },
+          "then": {
+            "properties": {
+              "parent": { "type": "null" }
+            },
+            "errorMessage": {
+              "parent": "ABC-R3: ApplicationStack MUST have no parent."
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "LogicalUnit" } } },
+          "then": {
+            "properties": {
+              "children": {
+                "minItems": 1,
+                "errorMessage": "ABC-R2: Logical Units MUST contain one or more Resource Groups."
+              }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "ResourceGroup" } } },
+          "then": {
+            "properties": {
+              "children": {
+                "maxItems": 0,
+                "errorMessage": "ABC-R10: Resource Groups MUST NOT contain child constructs."
+              }
+            }
+          }
+        }
+      ]
+    },
+
+    "ContractRules": {
+      "type": "object",
+      "description": "Contract validation rules.",
+      "properties": {},
+      "allOf": [
+        {
+          "properties": {
+            "inputs": {
+              "type": "object",
+              "errorMessage": "ABC-R24: Input Contracts MUST be immutable objects."
+            }
+          }
+        },
+        {
+          "properties": {
+            "outputs": {
+              "type": "object",
+              "errorMessage": "ABC-R23: Output Contracts MUST be declared explicitly."
+            }
+          }
+        }
+      ]
+    },
+
+    "DataFlowRules": {
+      "type": "object",
+      "description": "Data flow validation rules.",
+      "properties": {},
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "LogicalUnit" } } },
+          "then": {
+            "properties": {
+              "inputs": {
+                "type": "object"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## How Profiles Extend This Schema
+
+Profiles (e.g., Typescript CDK, Terraform) extend the monolithic schema using
+JSON Schema’s allOf mechanism.
+
+```json
+{
+  "$id": "https://schema.tiararodney.com/abc/profile/cdkts.schema.json",
+  "title": "ABC CDK TypeScript Profile",
+  "allOf": [
+    { "$ref": "https://abc-spec.org/schema/abc-schema.json" }
+  ],
+  "properties": {
+    "cdkts": {
+      "type": "object",
+      "description": "CDKTS-specific rules and metadata."
+    }
+  }
+}
+```
+
+## How The Schema is Consumed
+
+1. **Generate ABC structures from natural language**
+   The schema defines the allowed constructs and relationships.
+2. **Validate the architecture**
+   The schema + validation rules ensure correctness.
+3. **Compile into IaC**
+   Profiles map the schema to CDK, Terraform, Pulumi, etc.
+4. **Refactor architectures**
+   Agents can safely transform the schema because the rules are explicit.
+5. **Generate documentation**
+   The schema is a perfect source for diagrams and docs.