coulomb/helix-forge
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
helix-forge/wiki/OrthogonalArchitectureSchema.md

1471 lines
35 KiB
Markdown
Raw Normal View History

Established repo intent
2026-05-16 00:29:39 +02:00
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
Reference in a new issue Copy permalink