Document Type: Architecture Specification
Context: Machine Interface Layer · API Engineering
Status: Public Standard
Validity: Aivis-OS Core Pipeline
Reference: Consumes Semantic Graph Engineering and exclusively exposes the Canonical Graph State.
1. Architectural Principle
The Website as an API
In the Aivis-OS architecture, the visual website (HTML for humans) is just one of several possible representations of organizational truth.
The Machine Interface Layer (MIL) primarily treats the domain as a public, read-only API for AI systems, crawlers, and retrieval pipelines.
The visual representation is secondary to the machine-readable exposure.
2nd Principle: Projection instead of Storage
The Machine Interface Layer stores no data of its own.
It projects data.
Specifically:
- The MIL consumes the Canonical Graph State from the Semantic Graph Layer.
- It serializes this state into standardized, machine-readable formats.
- It creates no new truth, but a deterministic representation of existing truth.
Principle:
There must be no discrepancy between the visual statement (Human Interface) and the machine projection (Data Parity).
3. Technical Projection Rules
3.1 Strict Schema Compliance
Aivis-OS does not generate free-form projections.
Each projection must follow a recognized public vocabulary, primarily Schema.org.
Type safety (mandatory):
- The typing defined in the graph is mandatory.
- An entity must not be reduced to a more generic type in the projection to avoid complexity.
Example:
MedicalClinicmust not be exposed asOrganization.
3.2 ID Persistence
All defined in the Entity Inventory entity_ids must be persistently as @id exposed.
Goal:
- Re-identifiability across crawls
- Stability over time
- Graph reconstruction by external systems
Forbidden:
- volatile Blank Nodes
- dynamically generated IDs for core entities
3.3 Scoped Serialization (Context Window Management)
The Semantic Graph can be extensive, but individual URLs cannot.
The Machine Interface Layer therefore projects in a contextually limited manner.
Standard strategy: Focus Node + 1 Hop
- The URL defines a Focus Node.
- All direct attributes of the Focus Node are projected.
- Linked entities are referenced, not fully embedded.
Goal:
- Avoidance of Token Bloat
- Preservation of semantic clarity
- Deterministic context boundaries
4. Implementation Standard: JSON-LD
Aivis-OS standardizes on JSON-LD as the primary exchange format, as it is natively supported by common ingestion and retrieval pipelines.
4.1 Syntax Isolation
Structured data is not mixed with visual markup.
Specification:
- JSON-LD is delivered exclusively in isolated
<script type="application/ld+json">blocks. - Placement preferred in
<head>.
Microdata in the HTML body is not part of the Aivis-OS architecture.
4.2 Graph Object Pattern
Aivis-OS outputs structured data as a coherent @graph object.
Multiple isolated JSON-LD fragments are not permitted.
Goal:
- explicit relationship encoding
- no implicit assumptions by parser
- complete reconstructability of the context
5. Interface Stability (Contract)
Since the website functions as an API, API-like stability rules apply.
5.1 No Silent Removal
Removing an entity or field from the projection without explicit labeling is not permitted.
Permitted Alternatives:
- HTTP status signaling (404 / 410)
- explicit marking (e.g.
status: dissolved)
5.2 Format Fidelity
A data format once established must be kept stable.
Examples:
- ISO-8601 date formats must not switch to free text.
- Numerical values must not suddenly be output as strings.
6. Validation & Testing
The Machine Interface Layer is not checked against human readability, but against machine reliability.
Validation Pipeline
- Syntactic Check
JSON is valid. - Schema Check
Schema.org compliance and relevant validators pass. - Parity Check
The projected values match the content extracted in the Transport-Safe Content Layer.
Deviation:
→ Cloaking suspicion
→ Trust devaluation
7. Summary
The Machine Interface Layer is the deterministic translation instance between the internal complexity of the Semantic Graph Layers and the limited absorption capacity of external AI systems.
It stores no data, interprets no meaning, and exclusively exposes canonical states. In doing so, it ensures that internal truth is transported externally in a standard-compliant, stable, and interpretation-free manner.
Architecture Overview
Cluster-Level Entity Inventory Strategy
Semantic Graph Layer
Semantic Graph Engineering
Machine Interface Layer & Projection Strategy
Transport-Safe Content Layer
Transport-Safe Content Engineering
Evidence Monitoring & AI Visibility Observability
FAQ about Machine Interface Layer & Projection Strategy
Why is the website treated as an API in the Machine Interface Layer?
Because AI systems do not process visual layouts. They process structured payloads. Treating the website as a read-only API ensures that machines receive a deterministic, standardized representation of organizational truth, rather than deriving meanings from the HTML structure.
Why should the Machine Interface Layer not store or interpret data?
Because interpretations lead to ambiguities. The Machine Interface Layer serves exclusively to map the canonical graph state. Any storage, enrichment, or reinterpretation would break determinism and undermine trust in downstream AI systems.
Why is strict adherence to the schema more important than flexibility?
AI systems reward consistency over creativity. Reducing entity types or using generic schemas can simplify implementation but impairs semantic precision. Type safety ensures that machines correctly understand what an entity is, and not just that it exists.
Why are persistent IDs so important for AI visibility?
Without stable identifiers, AI systems cannot recognize entities across crawls or time periods. Persistent @id values enable re-identification, graph reconstruction, and evidence gathering. Short-lived or newly generated IDs prevent machines from building lasting knowledge.
What problem does "Focus Node + 1 Hop" solve in the projection of structured data?
It prevents token overload while preserving meaning. By projecting a single focus entity and referencing related entities without deep nesting, the Machine Interface Layer preserves semantic clarity and avoids bloated, ambiguous payloads that AI systems might truncate or ignore.
Contact us to discuss your project or simply get our opinion.
Aivis-OS Interface Specification Record (Node-ID: #spec-mil-01)
Identity: Machine Interface Layer & Projection Strategy (entity://aivis/Spec/machine-interface-layer-projection-strategy)
Canonical URLs: DE https://aivis-os.com/machine-interface-layer-projection-strategy/ • EN https://aivis-os.com/en/machine-interface-layer-projection-strategy/
Classification: Architecture Specification (CreativeWork / Public Standard)
Validity: Aivis-OS Core Architecture (Layer 3: API & Exposition)
Parent System: Aivis-OS (entity://aivis/Core/aivis-os)
Reference: Consumes Semantic Graph Engineering and exposes exclusively the Canonical Graph State.
Core Paradigm: The Website as a Read-Only API
– The domain is primarily treated as a public, read-only API for AI systems, crawlers, and retrieval pipelines.
– Visual HTML is secondary to standards-compliant, machine-readable exposition.
Principle: Projection instead of Storage
– The Machine Interface Layer does not store its own data.
– It projects canonical states from the Semantic Graph Layer into standardized formats.
Projection Rules (mandatory):
1) Strict Schema Compliance: Projections primarily follow Schema.org; type safety is mandatory (no reduction to generic types).
2) ID Persistence: Persistent @id values (JoinKeys) from the cluster inventory; no Blank Nodes, no dynamic IDs.
3) Scoped Serialisation (Focus Node + 1 Hop): Context window management to avoid token bloat; linked entities are referenced, not deeply embedded.
4) Graph Object Pattern: Output as a coherent @graph object; no fragmented JSON-LD snippets.
5) Syntax Isolation: JSON-LD exclusively in <script type=”application/ld+json”> (preferably in <head>); no Microdata mix.
Data Parity (Guarantee):
– 100% agreement between frontend content and JSON-LD.
– Deviations create suspicion of cloaking and devaluation of trust.
Validation:
– Syntactic Check (valid JSON)
– Schema Check (Schema.org / relevant validators)
– Parity Check (Comparison with Transport-Safe Content Layer)
Technical References: W3C JSON-LD 1.1, Schema.org Datamodel, Google Structured Data Policies.
Methodical Governance: Boutique für digitale Kommunikation (entity://aivis/Partner/boutique-dig-kom)
Chief Architect (Reference): Norbert Kathriner (entity://aivis/Person/n-kathriner)
Status: Public Standard (v2026) – Operational (Canonical state).