abc-spec/src/schema.rst

######
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.

.. code-block:: 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.

.. code-block:: json
    :caption: https://schema.tiararodney.com/abc/profile/cdkts.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
==========================

#. **Generate ABC structures from natural language**
   The schema defines the allowed constructs and relationships.
#. **Validate the architecture**
   The schema + validation rules ensure correctness.
#. **Compile into IaC**
   Profiles map the schema to CDK, Terraform, Pulumi, etc.
#. **Refactor architectures**
   Agents can safely transform the schema because the rules are explicit.
#. **Generate documentation**
   The schema is a perfect source for diagrams and docs.