OrthogonalArchitectureSchema *A schema to validate compute architectures* # Orthogonal Architecture Standard Schema v1.0.1 ## Structural Validation Below is a machine-readable schema for the **Orthogonal Architecture Standard** in **JSON Schema 2020-12** form, followed by a compact **YAML example** that validates against its structure. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.org/schemas/orthogonal-architecture-standard.schema.json", "title": "Orthogonal Architecture Standard", "description": "Machine-readable schema for describing architectures with the Orthogonal Architecture Standard.", "type": "object", "additionalProperties": false, "required": [ "standard", "version", "architecture" ], "properties": { "standard": { "type": "string", "const": "OrthogonalArchitectureStandard" }, "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" }, "architecture": { "$ref": "#/$defs/Architecture" } }, "$defs": { "Identifier": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]*$" }, "VsmSystem": { "type": "string", "enum": [ "S1", "S2", "S3", "S3*", "S4", "S5" ] }, "DimensionName": { "type": "string", "enum": [ "Stack", "Logic", "Plane", "Quality", "Capability", "Intelligence" ] }, "StackLevel": { "type": "string", "enum": [ "S1", "S2", "S3", "S4", "S5" ] }, "LogicLevel": { "type": "string", "enum": [ "L1", "L2", "L3", "L4" ] }, "PlaneLevel": { "type": "string", "enum": [ "P1", "P2", "P3" ] }, "QualityLevel": { "type": "string", "enum": [ "Q1", "Q2", "Q3", "Q4", "Q5", "Q6", "Q7" ] }, "CapabilityLevel": { "type": "string", "enum": [ "C1", "C2", "C3", "C4", "C5" ] }, "IntelligenceLevel": { "type": "string", "enum": [ "I1", "I2", "I3", "I4", "I5" ] }, "RelationType": { "type": "string", "enum": [ "realizes", "depends_on", "composes", "exposes", "governs", "observes", "hosted_on", "isolated_by", "augmented_by" ] }, "ElementType": { "type": "string", "enum": [ "Capability", "Service", "Application", "PlatformService", "DataStore", "ControlComponent", "ManagementInterface", "Integration", "Policy", "Automation", "IntelligenceComponent" ] }, "TagMap": { "type": "object", "additionalProperties": { "type": "string" } }, "DimensionPlacement": { "type": "object", "additionalProperties": false, "required": [ "dimension", "level" ], "properties": { "dimension": { "$ref": "#/$defs/DimensionName" }, "level": { "type": "string" } }, "allOf": [ { "if": { "properties": { "dimension": { "const": "Stack" } } }, "then": { "properties": { "level": { "$ref": "#/$defs/StackLevel" } } } }, { "if": { "properties": { "dimension": { "const": "Logic" } } }, "then": { "properties": { "level": { "$ref": "#/$defs/LogicLevel" } } } }, { "if": { "properties": { "dimension": { "const": "Plane" } } }, "then": { "properties": { "level": { "$ref": "#/$defs/PlaneLevel" } } } }, { "if": { "properties": { "dimension": { "const": "Quality" } } }, "then": { "properties": { "level": { "$ref": "#/$defs/QualityLevel" } } } }, { "if": { "properties": { "dimension": { "const": "Capability" } } }, "then": { "properties": { "level": { "$ref": "#/$defs/CapabilityLevel" } } } }, { "if": { "properties": { "dimension": { "const": "Intelligence" } } }, "then": { "properties": { "level": { "$ref": "#/$defs/IntelligenceLevel" } } } } ] }, "ElementRef": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "$ref": "#/$defs/Identifier" } } }, "Relation": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "source", "target" ], "properties": { "id": { "$ref": "#/$defs/Identifier" }, "type": { "$ref": "#/$defs/RelationType" }, "source": { "$ref": "#/$defs/Identifier" }, "target": { "$ref": "#/$defs/Identifier" }, "description": { "type": "string" }, "vsm_tags": { "type": "array", "items": { "$ref": "#/$defs/VsmSystem" }, "uniqueItems": true }, "tags": { "$ref": "#/$defs/TagMap" } } }, "Element": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "type", "placements" ], "properties": { "id": { "$ref": "#/$defs/Identifier" }, "name": { "type": "string" }, "type": { "$ref": "#/$defs/ElementType" }, "description": { "type": "string" }, "placements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/DimensionPlacement" } }, "vsm_tags": { "type": "array", "items": { "$ref": "#/$defs/VsmSystem" }, "uniqueItems": true }, "owners": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "contracts": { "type": "array", "items": { "$ref": "#/$defs/Identifier" }, "uniqueItems": true }, "quality_requirements": { "type": "array", "items": { "$ref": "#/$defs/QualityLevel" }, "uniqueItems": true }, "tags": { "$ref": "#/$defs/TagMap" }, "metadata": { "type": "object" } } }, "DimensionDefinition": { "type": "object", "additionalProperties": false, "required": [ "name", "levels" ], "properties": { "name": { "$ref": "#/$defs/DimensionName" }, "levels": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "code", "name" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "vsm_tags": { "type": "array", "items": { "$ref": "#/$defs/VsmSystem" }, "uniqueItems": true } } } } } }, "Architecture": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "dimensions", "elements", "relations" ], "properties": { "id": { "$ref": "#/$defs/Identifier" }, "name": { "type": "string" }, "description": { "type": "string" }, "dimensions": { "type": "array", "minItems": 6, "items": { "$ref": "#/$defs/DimensionDefinition" } }, "elements": { "type": "array", "items": { "$ref": "#/$defs/Element" } }, "relations": { "type": "array", "items": { "$ref": "#/$defs/Relation" } }, "principles": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "author": { "type": "string" }, "notes": { "type": "string" } } } }, "metadata": { "type": "object" } } } } } ``` Example instance in YAML: ```yaml standard: OrthogonalArchitectureStandard version: "1.0" architecture: id: orthogonal-architecture-example name: Orthogonal Architecture Example description: Example instance for a Kubernetes-based SaaS platform. dimensions: - name: Stack levels: - code: S1 name: Infrastructure Substrate vsm_tags: [S1] - code: S2 name: Cluster Runtime vsm_tags: [S2] - code: S3 name: Platform Services vsm_tags: [S1] - code: S4 name: Developer Enablement vsm_tags: [S4] - code: S5 name: Workloads & Experience Endpoints vsm_tags: [S1] - name: Logic levels: - code: L1 name: Capability Domain vsm_tags: [S5] - code: L2 name: Service Realization vsm_tags: [S1] - code: L3 name: Composition & Integration vsm_tags: [S2] - code: L4 name: Solution Layer vsm_tags: [S1] - name: Plane levels: - code: P1 name: Workload Plane vsm_tags: [S1] - code: P2 name: Control Plane vsm_tags: [S3] - code: P3 name: Management Plane vsm_tags: [S5] - name: Quality levels: - code: Q1 name: Security & Compliance vsm_tags: [S5] - code: Q2 name: Observability vsm_tags: [S3*] - code: Q3 name: Operability & Resilience vsm_tags: [S3] - code: Q4 name: Isolation & Tenancy vsm_tags: [S2] - code: Q5 name: Performance & Scalability vsm_tags: [S3] - code: Q6 name: Cost & Efficiency vsm_tags: [S3] - code: Q7 name: Governance & Change vsm_tags: [S5] - name: Capability levels: - code: C1 name: Capability Model vsm_tags: [S5] - code: C2 name: Capability Contract vsm_tags: [S2] - code: C3 name: Capability Realization vsm_tags: [S1] - code: C4 name: Shared Platform Capabilities vsm_tags: [S3] - code: C5 name: Business Capabilities vsm_tags: [S1] - name: Intelligence levels: - code: I1 name: Deterministic Automation vsm_tags: [S3] - code: I2 name: Language Interaction vsm_tags: [S4] - code: I3 name: Knowledge & Reasoning vsm_tags: [S4] - code: I4 name: Assisted Adaptation vsm_tags: [S4] - code: I5 name: Agentic Delegation vsm_tags: [S4, S5] elements: - id: capability.customer-billing name: Customer Billing type: Capability description: Billing capability for customer subscriptions and invoices. placements: - dimension: Logic level: L1 - dimension: Capability level: C5 vsm_tags: [S1, S5] owners: [Finance Platform Team] quality_requirements: [Q1, Q3, Q7] - id: service.billing-api name: Billing API type: Service placements: - dimension: Stack level: S5 - dimension: Logic level: L2 - dimension: Plane level: P1 - dimension: Capability level: C3 vsm_tags: [S1] owners: [Finance Platform Team] quality_requirements: [Q1, Q2, Q3, Q5] - id: datastore.billing-postgres name: Billing PostgreSQL type: DataStore placements: - dimension: Stack level: S3 - dimension: Plane level: P1 vsm_tags: [S1, S3] quality_requirements: [Q1, Q3, Q4, Q5] - id: control.gitops name: GitOps Controller type: ControlComponent placements: - dimension: Plane level: P2 - dimension: Stack level: S4 vsm_tags: [S3] quality_requirements: [Q1, Q3, Q7] - id: mgmt.developer-portal name: Developer Portal type: ManagementInterface placements: - dimension: Plane level: P3 - dimension: Stack level: S4 vsm_tags: [S5] quality_requirements: [Q1, Q7] - id: intelligence.deployment-copilot name: Deployment Copilot type: IntelligenceComponent placements: - dimension: Intelligence level: I4 - dimension: Plane level: P3 vsm_tags: [S4] quality_requirements: [Q1, Q2, Q7] relations: - id: r1 type: realizes source: service.billing-api target: capability.customer-billing vsm_tags: [S1] - id: r2 type: depends_on source: service.billing-api target: datastore.billing-postgres vsm_tags: [S1] - id: r3 type: governs source: control.gitops target: service.billing-api vsm_tags: [S3] - id: r4 type: augmented_by source: mgmt.developer-portal target: intelligence.deployment-copilot vsm_tags: [S4] principles: - Separate dimensions. - Capabilities are stable intent; services are realizations. - AI must operate through the control plane. sources: - title: Kubernetes Components url: https://kubernetes.io/docs/concepts/overview/components/ - title: Kubernetes Multi-Tenancy url: https://kubernetes.io/docs/concepts/security/multi-tenancy/ - title: Platform Strategy author: Gregor Hohpe ``` A useful next step is to add a second schema layer for stricter semantic validation, such as requiring at least one `Logic` placement for every `Service`, or requiring every `IntelligenceComponent` at `I5` to have a `governs` or `operates_via` style relation through a control component. ## Semantic Validation Below is a **second schema layer** for stricter semantic validation. The cleanest way to do this is to keep: * **Layer 1** = structural schema in JSON Schema * **Layer 2** = semantic rule layer in JSON Schema as far as possible, plus a small set of explicit validation rules that most validators can implement easily Because plain JSON Schema is good at structure but limited at graph-style cross-reference semantics, I’ll give you: 1. an **extended JSON Schema layer** with stronger constraints 2. a **semantic rule profile** for validators 3. an updated **machine-readable convention block** you can attach to the standard --- # Orthogonal Architecture Standard ## Semantic Validation Layer (Layer 2) ## 1. Purpose The second schema layer defines **semantic consistency rules** beyond basic structural validation. It ensures that architecture descriptions are not only syntactically valid, but also **architecturally meaningful**. This layer validates: * placement consistency * required dimension participation by element type * governance constraints * intelligence/control-plane coupling * relation sanity rules --- ## 2. Validation approach Use a **two-layer validation model**: ### Layer 1 — Structural validation Validate JSON/YAML documents against the base JSON Schema. ### Layer 2 — Semantic validation Validate the same document against: * extended JSON Schema constraints where possible * explicit semantic rules for cross-element consistency --- # 3. Extended JSON Schema Layer This schema is intended as a companion to the first schema. It assumes the base schema already exists. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.org/schemas/orthogonal-architecture-standard.semantic-layer.schema.json", "title": "Orthogonal Architecture Standard - Semantic Validation Layer", "description": "Second-layer semantic constraints for the Orthogonal Architecture Standard.", "type": "object", "allOf": [ { "$ref": "https://example.org/schemas/orthogonal-architecture-standard.schema.json" } ], "$defs": { "ServiceElement": { "type": "object", "properties": { "type": { "const": "Service" } }, "required": ["type"] }, "ApplicationElement": { "type": "object", "properties": { "type": { "const": "Application" } }, "required": ["type"] }, "CapabilityElement": { "type": "object", "properties": { "type": { "const": "Capability" } }, "required": ["type"] }, "ControlComponentElement": { "type": "object", "properties": { "type": { "const": "ControlComponent" } }, "required": ["type"] }, "ManagementInterfaceElement": { "type": "object", "properties": { "type": { "const": "ManagementInterface" } }, "required": ["type"] }, "IntelligenceComponentElement": { "type": "object", "properties": { "type": { "const": "IntelligenceComponent" } }, "required": ["type"] } }, "properties": { "architecture": { "type": "object", "properties": { "elements": { "type": "array", "items": { "allOf": [ { "if": { "properties": { "type": { "const": "Service" } } }, "then": { "allOf": [ { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Logic" }, "level": { "const": "L2" } }, "required": ["dimension", "level"] } } } }, { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Plane" }, "level": { "const": "P1" } }, "required": ["dimension", "level"] } } } } ] } }, { "if": { "properties": { "type": { "const": "Application" } } }, "then": { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Logic" }, "level": { "enum": ["L2", "L4"] } }, "required": ["dimension", "level"] } } } } }, { "if": { "properties": { "type": { "const": "Capability" } } }, "then": { "allOf": [ { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Logic" }, "level": { "const": "L1" } }, "required": ["dimension", "level"] } } } }, { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Capability" } }, "required": ["dimension"] } } } } ] } }, { "if": { "properties": { "type": { "const": "ControlComponent" } } }, "then": { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Plane" }, "level": { "const": "P2" } }, "required": ["dimension", "level"] } } } } }, { "if": { "properties": { "type": { "const": "ManagementInterface" } } }, "then": { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Plane" }, "level": { "const": "P3" } }, "required": ["dimension", "level"] } } } } }, { "if": { "properties": { "type": { "const": "IntelligenceComponent" } } }, "then": { "properties": { "placements": { "contains": { "type": "object", "properties": { "dimension": { "const": "Intelligence" } }, "required": ["dimension"] } } } } } ] } }, "relations": { "type": "array", "items": { "allOf": [ { "if": { "properties": { "type": { "const": "realizes" } } }, "then": { "required": ["source", "target"] } }, { "if": { "properties": { "type": { "const": "governs" } } }, "then": { "required": ["source", "target"] } }, { "if": { "properties": { "type": { "const": "augmented_by" } } }, "then": { "required": ["source", "target"] } } ] } } } } } } ``` --- # 4. Semantic rule profile These rules go beyond what JSON Schema can fully guarantee on its own. They should be treated as **normative semantic constraints**. ## R1. Service placement rule Every element of type `Service` MUST have: * one `Logic/L2` placement * one `Plane/P1` placement ## R2. Capability placement rule Every element of type `Capability` MUST have: * one `Logic/L1` placement * one `Capability/C1`, `C4`, or `C5` placement ## R3. Control component rule Every element of type `ControlComponent` MUST have: * one `Plane/P2` placement ## R4. Management interface rule Every element of type `ManagementInterface` MUST have: * one `Plane/P3` placement ## R5. Intelligence placement rule Every element of type `IntelligenceComponent` MUST have: * one `Intelligence/I1–I5` placement ## R6. Realization rule Every `Service` or `Application` SHOULD participate in at least one `realizes` relation pointing to a `Capability`. Normative strength: * **MUST** for production models * **SHOULD** for drafts ## R7. Governance rule Every element placed at: * `Intelligence/I5` MUST be governed through at least one relation to a `ControlComponent`. Acceptable patterns: * `ControlComponent governs IntelligenceComponent` * `IntelligenceComponent depends_on ControlComponent` * `ManagementInterface augmented_by IntelligenceComponent` plus `ManagementInterface depends_on ControlComponent` More strictly: * an I5 component MUST have at least one path to a P2 control component ## R8. Observability rule Every `Service`, `Application`, and `PlatformService` SHOULD reference `Q2` in `quality_requirements`. ## R9. Security rule Every `ControlComponent`, `ManagementInterface`, and `IntelligenceComponent` MUST reference `Q1` and `Q7` in `quality_requirements`. ## R10. Hosted workload rule Every element of type: * `Service` * `Application` * `PlatformService` * `DataStore` SHOULD have at least one `hosted_on` relation or a `Stack` placement. ## R11. Relation typing rule `realizes` relations MUST connect: * source: `Service` or `Application` * target: `Capability` ## R12. Governance relation typing rule `governs` relations MUST originate from: * `ControlComponent` * `Policy` and MUST target one of: * `Service` * `Application` * `PlatformService` * `ManagementInterface` * `IntelligenceComponent` ## R13. Augmentation typing rule `augmented_by` relations MUST point to an `IntelligenceComponent`. ## R14. Unique placement rule An element MUST NOT contain duplicate placements with the same dimension and level. ## R15. Intelligence-control rule Any element with `Intelligence/I4` or `Intelligence/I5` SHOULD be linked to at least one of: * `ControlComponent` * `ManagementInterface` * `Policy` ## R16. Plane consistency rule No element except `ControlComponent`, `ManagementInterface`, or `Policy` SHOULD be placed directly in `Plane/P2` or `Plane/P3`. --- # 5. Machine-readable semantic rules block This block is not a full validator by itself, but it gives you a machine-readable policy profile that tools can interpret. ```yaml semantic_rules: version: "1.0" profile: orthogonal-architecture-semantic-rules rules: - id: R1 name: service-placement severity: error applies_to: Service requires_placements: - { dimension: Logic, level: L2 } - { dimension: Plane, level: P1 } - id: R2 name: capability-placement severity: error applies_to: Capability requires_placements: - { dimension: Logic, level: L1 } requires_one_of_placements: - { dimension: Capability, level: C1 } - { dimension: Capability, level: C4 } - { dimension: Capability, level: C5 } - id: R3 name: control-component-plane severity: error applies_to: ControlComponent requires_placements: - { dimension: Plane, level: P2 } - id: R4 name: management-interface-plane severity: error applies_to: ManagementInterface requires_placements: - { dimension: Plane, level: P3 } - id: R5 name: intelligence-placement severity: error applies_to: IntelligenceComponent requires_dimension: Intelligence - id: R6 name: service-realizes-capability severity: warning applies_to_any_of: - Service - Application requires_relation: type: realizes direction: outgoing target_type: Capability - id: R7 name: i5-governed-through-control-plane severity: error applies_to: IntelligenceComponent when_has_placement: dimension: Intelligence level: I5 requires_relation_any: - type: depends_on direction: outgoing target_type: ControlComponent - type: governs direction: incoming source_type: ControlComponent - type: augmented_by direction: incoming source_type: ManagementInterface - id: R8 name: runtime-observability severity: warning applies_to_any_of: - Service - Application - PlatformService requires_quality: - Q2 - id: R9 name: governed-sensitive-components severity: error applies_to_any_of: - ControlComponent - ManagementInterface - IntelligenceComponent requires_quality: - Q1 - Q7 - id: R10 name: hostable-runtime-element severity: warning applies_to_any_of: - Service - Application - PlatformService - DataStore requires_any: placements_in_dimension: - Stack outgoing_relations: - type: hosted_on - id: R11 name: realizes-typing severity: error applies_to_relation: realizes source_type_any_of: - Service - Application target_type: Capability - id: R12 name: governs-typing severity: error applies_to_relation: governs source_type_any_of: - ControlComponent - Policy target_type_any_of: - Service - Application - PlatformService - ManagementInterface - IntelligenceComponent - id: R13 name: augmented-by-typing severity: error applies_to_relation: augmented_by target_type: IntelligenceComponent - id: R14 name: unique-placements severity: error applies_to: "*" forbids_duplicate_placements: true - id: R15 name: adaptive-intelligence-governance-link severity: warning applies_to: IntelligenceComponent when_has_placement_any: - { dimension: Intelligence, level: I4 } - { dimension: Intelligence, level: I5 } requires_relation_any: - type: depends_on direction: outgoing target_type: ControlComponent - type: depends_on direction: outgoing target_type: ManagementInterface - type: governs direction: incoming source_type: Policy - id: R16 name: restricted-plane-placement severity: warning applies_to_any_of: - Service - Application - PlatformService - DataStore forbids_placements: - { dimension: Plane, level: P2 } - { dimension: Plane, level: P3 } ``` --- # 6. Recommended validator behavior A validator should process the document in this order: ## Phase 1 — structural validation Validate against the base JSON Schema. ## Phase 2 — semantic indexing Build in-memory indexes for: * elements by id * elements by type * placements by dimension * relations by source/target ## Phase 3 — semantic checks Apply rules R1–R16. ## Phase 4 — report output Return: * `errors` * `warnings` * `info` Recommended format: ```yaml validation_result: valid: false errors: - rule: R1 element: service.billing-api message: "Service must include Logic/L2 and Plane/P1 placements." - rule: R11 relation: r7 message: "Relation 'realizes' must target a Capability." warnings: - rule: R8 element: service.billing-api message: "Runtime service should include Q2 Observability." ``` --- # 7. Optional stricter production profile For production-grade architecture models, I recommend upgrading some SHOULD-like checks to MUST. ## Production profile changes * R6 becomes `error` * R8 becomes `error` * R10 becomes `error` * R15 becomes `error` Machine-readable profile: ```yaml validation_profiles: draft: overrides: {} production: overrides: R6: { severity: error } R8: { severity: error } R10: { severity: error } R15: { severity: error } ``` --- # 8. Practical note If you want full automated semantic validation, JSON Schema alone is not ideal for all graph constraints. The best practical combination is: * **JSON Schema** for structure * **custom semantic validator** for graph rules * optionally **SHACL** later if you want RDF/knowledge-graph style validation That gives you a robust path without overcomplicating the first implementation. The next useful step would be a **reference validator implementation in Python** that reads YAML and applies both layers. xxx