SEM-FM
ZAYAZ Semantic Frontmatter Schema
The ZAYAZ semantic frontmatter schema adds a machine-readable ontology and graph layer to every MDX document in the ZAYAZ documentation system.
Its purpose is to make the documentation usable not only by humans in Docusaurus, but also by Ask ZARA, future graph visualizers, enrichment agents, Obsidian exports, and potential graph databases such as Neo4j.
This turns the MDX corpus into a structured knowledge layer for ZAYAZ.
Strategic Purpose
The additional frontmatter fields allow each document to function as a graph node.
Over time, Ask ZARA will be able to use these fields to:
- identify system components;
- understand dependencies;
- traverse relationships;
- explain how modules connect;
- support impact analysis;
- generate graph visualizations;
- distinguish inferred relationships from verified ones;
- support AI-assisted ontology enrichment.
The fields are intentionally separated from ordinary Docusaurus metadata so the documentation can evolve into a semantic governance graph without breaking existing navigation, links, or sidebar behavior.
Identifier Fields
semantic_id
The semantic_id is the stable, graph-native identifier for the document or component.
Example:
semantic_id: zayaz.sssr.json.registry.diagrams
This field is intended for:
- Ask ZARA graph traversal;
- ontology mapping;
- graph database export;
- semantic search;
- cross-document relationship resolution;
- future API and registry references.
The existing id field remains unchanged for backward compatibility.
short_id
The short_id is the compact human-readable identifier.
Example:
short_id: ZSSR
This is useful for:
- diagrams;
- UI labels;
- engineering discussions;
- graph node labels;
- Ask ZARA summaries.
In some documents it may initially match id, but it may diverge later when semantic_id becomes more formal.
canonical_name
The canonical_name is the authoritative ontology-level name of the component or document.
Example:
canonical_name: ZAYAZ Smart System Router
This is different from title, which may be optimized for documentation display.
canonical_name is used for:
- Ask ZARA entity recognition;
- alias resolution;
- semantic deduplication;
- white-label consistency;
- long-term ontology governance.
aliases
The aliases field contains alternative names, abbreviations, or common references.
Example:
aliases:
- Smart Router
- ZSSR Router
- System Router
This improves:
- Ask ZARA retrieval;
- fuzzy matching;
- user prompt interpretation;
- multilingual or white-label terminology mapping.
Ontology Fields
ontology_type
Defines what kind of semantic object the document represents.
Example:
ontology_type:
- micro_engine
- validation_engine
Typical values may include:
- module
- micro_engine
- registry
- router
- ai_agent
- workflow
- policy
- framework
- api
- trust_layer
- documentation_schema
This allows graph views to cluster and filter documents by type.
ontology_version
Defines the schema version used by the semantic metadata.
Example:
ontology_version: 1
This supports future upgrades to the ontology without breaking older documents.
Relationship Fields
These fields describe how one document or component connects to others.
All relationship values should preferably use semantic_id values.
related
General semantic association.
Example:
related:
- zayaz.zara
- zayaz.sssr
Use this when two concepts are connected but the relationship is not strictly dependency, input, output, or governance.
depends_on
Components, systems, registries, or processes required for this item to function.
Example:
depends_on:
- zayaz.altd
- zayaz.sssr
This is important for:
- impact analysis;
- architecture risk mapping;
- dependency visualization;
- change management.
interfaces_with
Systems or components this document directly interacts with.
Example:
interfaces_with:
- zayaz.zadif
- zayaz.zaam
This is useful for integration mapping and system boundary analysis.
consumes
Inputs required or used by the component.
Example:
consumes:
- mdx_frontmatter
- registry_metadata
This field supports lineage and data-flow mapping.
produces
Outputs generated by the component.
Example:
produces:
- semantic_graph_nodes
- graph_relationships
This field supports provenance, reporting, and downstream dependency analysis.
governed_by
Policies, governance systems, standards, or control layers that apply to the document or component.
Example:
governed_by:
- zayaz.ai_governance
- zayaz.altd
This is important for auditability and compliance traceability.
frameworks
External or internal frameworks associated with the document.
Example:
frameworks:
- CSRD
- ESRS
- EU Taxonomy
This supports regulatory navigation and framework-specific graph views.
Graph Metadata
graph
The graph object defines how the document participates in the ZAYAZ semantic graph.
Example:
graph:
node: true
enrichable: true
confidence: unverified
graph.node
Defines whether the document should be treated as a graph node.
node: true
Most MDX documents should be graph nodes.
graph.enrichable
Defines whether enrichment agents are allowed to add or improve semantic relationships.
enrichable: true
This should usually remain true unless the document is locked for governance reasons.
graph.confidence
Defines the current trust level of the graph metadata.
Recommended values:
unverified
inferred
agent-enriched
human-reviewed
authoritative
Meaning:
| Value | Meaning |
|---|---|
| unverified | Field exists but has not yet been reviewed or enriched |
| inferred | Relationship was inferred from content or structure |
| agent-enriched | Added by an approved enrichment agent |
| human-reviewed | Reviewed by a human editor or architect |
| authoritative | Approved as canonical ontology metadata |
Recommended Baseline Block
Every MDX document should contain the following baseline semantic block:
semantic_id:
short_id:
canonical_name:
aliases: []
ontology_type: []
ontology_version: 1
related: []
depends_on: []
interfaces_with: []
consumes: []
produces: []
governed_by: []
frameworks: []
graph:
node: true
enrichable: true
confidence: unverified
Enrichment Strategy
During initial migration, many fields may remain empty.
This is intentional.
The current priority is to:
- transfer the complete ZAYAZ manual into Docusaurus;
- preserve existing documentation structure;
- add the semantic field scaffold consistently;
- allow Ask ZARA to index the full corpus;
- use enrichment agents to populate relationships later;
- validate enriched metadata through schema checks and human review.
This prevents manual over-engineering during migration while preparing the corpus for graph-native intelligence.
Long-Term Direction
The semantic frontmatter schema is the foundation for Ask ZARA becoming a graph navigator.
Future capabilities may include:
- “Show all systems depending on ZSSR.”
- “Which micro engines produce assurance proofs?”
- “Which documents are governed by AI governance?”
- “Visualize all components connected to CSRD.”
- “Show the trust lineage from signal input to report output.”
- “Find orphaned modules with no dependencies or outputs.”
- “Identify high-risk components with unverified graph metadata.”
The long-term architecture is:
MDX Documentation
↓
Semantic Frontmatter
↓
Ask ZARA Index
↓
Graph Registry
↓
Graph Visualization
↓
AI-Assisted Navigation and Governance
This makes ZAYAZ documentation an operational intelligence layer, not just a static manual.