generated from coulomb/repo-seed
1471 lines
35 KiB
Markdown
1471 lines
35 KiB
Markdown
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
|