SML (Semantic Markup Language) Specification v1.1

Status: Standards Track | Date: 2026-08-03 | Version: 1.1 | Classification: Experimental Part of: Open Memory Specification (OMS) v1.5

Table of Contents

• Abstract

1. What is SML?
2. Structural Rules
3. Comprehensive Example — All 12 Grain Types
4. Progressive Disclosure

• Appendix A: Relationship to CAL
• Appendix B: Version History

Abstract

SML (Semantic Markup Language) is a flat, tag-based markup format optimized for LLM context consumption. It is the default output format for CAL ASSEMBLE statements and can be consumed directly by any LLM without an XML processor.

SML uses tag syntax as a semantic signalling device — the tag name tells the LLM what kind of information follows (using OMS grain types as tag names), the attributes carry lightweight decision metadata, and the element text is natural language content.

SML is part of the Open Memory Specification (OMS) v1.5 family. The FORMAT system that produces SML output is defined in the Context Assembly Language (CAL) specification.

1. What is SML?

SML (Semantic Markup Language) is a flat, tag-based markup format defined by CAL specifically for LLM context consumption. It is not XML. SML uses the tag syntax as a semantic signalling device — the tag name tells the LLM what kind of information follows; the attributes carry lightweight decision metadata; the element text is natural language content. SML does not require, and is not validated by, an XML processor.

SML is the default format for the structured preset (alias sml) in CAL's FORMAT system.

2. Structural Rules

The formatted output uses a flat, semantic structure:

1. Tag names ARE the grain type. No generic <grain> wrapper — use <fact>, <goal>, <event>, etc.
2. No group wrappers. No <source>, <facts>, or other container elements. Whitespace separates grain groups.
3. Storage internals never appear. No hashes, counts, namespaces, or OMS-internal fields.
4. Text content reads as natural language. The element text is the projected content, not decomposed triples.
5. One envelope element. The <context> wrapper carries only the intent attribute. It is the sole container.

3. Comprehensive Example — All 12 Grain Types

The following example shows a single assembled context covering every grain type. The scenario: an agent helping alice prepare her Q1 engineering review.

<context intent="helping alice prepare her Q1 engineering review">
 
  <fact subject="alice" confidence="0.95">prefers dark mode in all tools</fact>
  <fact subject="alice" confidence="0.88">requires keyboard shortcuts for productivity</fact>
  <fact subject="alice" confidence="0.82">works best in deep-focus blocks of 90 minutes</fact>
 
  <goal subject="alice" state="active" deadline="2026-03-15">complete Q1 engineering review presentation</goal>
  <goal subject="alice" state="active">reduce P0 incident rate by 20% in Q2</goal>
 
  <event role="user" time="10m ago">Can you help me pull together the Q1 metrics?</event>
  <event role="assistant" time="10m ago">Sure — retrieving deployment counts, incident data, and velocity now.</event>
  <event role="user" time="8m ago">Focus on the reliability numbers first.</event>
 
  <tool tool="query_metrics" phase="completed">retrieved 47 deployments and 3 P0 incidents for Q1 2026</tool>
  <tool tool="search_docs" phase="completed">found Q1 review template in confluence/engineering/reviews</tool>
 
  <observation observer="system">alice opened incident-dashboard at 09:14 UTC</observation>
  <observation observer="system" source="calendar">Q1 review presentation scheduled for 2026-03-15 14:00 UTC</observation>
 
  <reasoning type="deductive">alice is prioritising reliability given 3 P0 incidents; lead with incident reduction narrative</reasoning>
  <reasoning type="abductive">low velocity in week 8 likely caused by the infra migration; flag as contextual outlier</reasoning>
 
  <state context="q1_review_prep">outlining slides: 1. headline metrics  2. incident retrospective  3. velocity trend  4. Q2 goals</state>
 
  <workflow trigger="review_prep_requested">retrieve_metrics -> identify_narrative -> draft_outline -> populate_data -> send_for_review</workflow>
 
  <consensus threshold="3" count="4">Q1 deployment frequency improved 18% over Q4 2025</consensus>
 
  <consent action="granted" grantor="alice" grantee="agent">access engineering metrics dashboards for review preparation</consent>
 
  <skill name="metrics_review" proficiency="0.82" domain="software">summarise quarterly engineering metrics and surface the reliability narrative</skill>
 
  <recommendation target="entity:alice/velocity" severity="low">consolidate 2 duplicate "week 8 velocity" observations into one</recommendation>
 
</context>

Each element maps directly to one grain type. The LLM reads the tag to understand the epistemic status of the content — a <fact> carries a known confidence, a <reasoning> signals inference, a <consent> signals an explicit permission grant, a <skill> signals a packaged, reusable capability, a <recommendation> signals a proposed, reviewable change — without needing to parse attribute schemas or understand OMS internals.

4. Progressive Disclosure

Progressive disclosure controls metadata density on a flat structure, not nesting depth. The element shape stays the same across all levels — only the number of attributes changes.

Appendix A: Relationship to CAL

SML is produced by the CAL ASSEMBLE statement's FORMAT system. The CAL specification defines:

• The structured / sml preset that selects SML output
• The Content Projection Model (CAL §10.3) that maps grain fields to SML elements
• Template variables and custom templates for SML output
• Progressive disclosure levels (summary, standard, full)

See the CAL specification for the complete FORMAT system, template engine, and ASSEMBLE statement semantics.

Appendix B: Version History

Document Status: This is the SML (Semantic Markup Language) Specification v1.1. SML is part of the Open Memory Specification (OMS) v1.5 — see SPECIFICATION.md.

Last Updated: 2026-08-03 License: This specification is offered under the Open Web Foundation Final Specification Agreement (OWFa 1.0) Copyright: Public Domain (CC0 1.0 Universal)