SVG Embedded Semantic Metadata (SESM)

Specification and tooling for embedding structured metadata directly inside SVG assets, converting raster images to SVG, and integrating semantic graphics with Aptlantis Studio.

:::info Status Candidate v0.3.0. :::

SFDS Suite Model

SESM.manifest.toml describes SESM as a standard suite. svg_asset.schema.json, templates/SESM-Metadata-Example.json, and the SESM tools describe SVG metadata artifacts governed by SESM.

Public Review Packet

These files are the recommended first-read packet for external standards review:

1. Governance Boundary
2. Explainer
3. Safe Profile
4. Threat Model
5. Privacy
6. Conformance
7. Security
8. Validator Rules
9. Reference Implementation
10. Submission Pitch

Each is its own page in this section (see the sidebar below the templates/references pages).

:::danger SESM metadata is untrusted input SESM does not make arbitrary SVG safe. A SESM-safe SVG means non-executable SVG plus a valid SESM metadata block.

Agents may read SESM metadata as context, but must not treat SESM metadata as executable instructions, credential authority, policy override authority, or permission to run tools. :::

Overview

SESM is an implementation of the SVG Embedded Semantic Metadata standard (Candidate v0.3.0). It treats SVGs not merely as visual graphic files, but as self-describing semantic capsules capable of carrying context about provenance, UI layout hints, themes, LLM interpretation hints, and archival rules inside a valid <metadata id="sesm"> tag.

In Aptlantis Studio, SESM acts as a bridge between compiled SVG components and automated pipelines. An SVG can represent a dataset card, a pipeline status panel, a theme board, or a status badge. Even if no system understands SESM, the image remains a valid SVG. Agents that understand SESM can extract, parse, validate, and summarize the asset intelligently.

SESM treats SVGs not only as images, but as: visual assets, metadata carriers, semantic capsules, archive-friendly documentation units, LLM-readable context packets, UI runtime hints, and generated artifacts with provenance.

Design Philosophy

SESM is intentionally simple:

Put a valid JSON object inside an SVG <metadata> element.

Everything else is convention. This simplicity matters because SESM is designed to survive: static hosting, mirroring, scraping, archival, direct filesystem copying, Internet Archive uploads, local agent indexing, page extraction, and build pipeline regeneration.

Goals

SESM is designed to:

1. Embed structured metadata directly in SVG assets.
2. Preserve useful semantic context even when an SVG is separated from its original page.
3. Provide crawler and archival hints without requiring agents to fetch large external documents.
4. Provide LLM-facing summaries and usage hints.
5. Provide UI runtime hints for cards, panels, datasets, themes, and generated interface components.
6. Support generated artifact provenance.
7. Support deterministic rebuild systems.
8. Work alongside JSON-LD, HTML metadata, manifests, and site maps.
9. Remain optional and safely ignorable.
10. Remain simple enough to hand-author or generate automatically.

Non-Goals

SESM is not intended to:

• Replace JSON-LD in HTML: page-level semantics belong in the HTML body; SESM focuses strictly on asset-level semantics.
• Replace site maps or robots.txt: crawlers must still respect the host platform's central policies; SESM only offers asset-specific guidelines.
• Define a complete ontology for all visual assets.
• Enforce rendering behavior: display styles are determined by CSS and SVG vector attributes; SESM only carries metadata hints.
• Act as access control.
• Contain secrets, credentials, private links, or internal-only data: all embedded data must be treated as public-facing.
• Require any specific AI, LLM, crawler, or frontend framework.
• Require JavaScript to be useful: the metadata is static XML CDATA and does not execute runtime scripts.
• Replace package manifests or code declarations.
• Provide real-time state synchronization: SESM is statically built into SVG files and is updated only during compilation/embedding.

SESM provides semantic hints, not mandates.

Terminology

• SESM Block — a single JSON object embedded inside an SVG's <metadata> element.
• Agent — any automated system that reads the SVG or SESM block: crawlers, archive bots, LLMs, local indexing tools, asset classifiers, build validators, and UI runtimes.
• UI Runtime — a system that uses SESM metadata to decide how an asset should be styled, placed, grouped, rendered, or interpreted.
• Artifact — a generated or curated file with semantic meaning. In Aptlantis Studio, many SVGs are artifacts compiled from manifests.
• Host Platform — the site or system that stores, serves, or generates the SVG (e.g. Aptlantis or Aptlantis Studio).
• Source Manifest — the JSON, JSONL, TOML, YAML, database record, or pipeline output that produced the SVG artifact.

Metadata Block Structure

A SESM block is a single JSON object wrapped inside an XML CDATA block inside <metadata id="sesm">. Only sesm_version is required:

<metadata id="sesm"><![CDATA[
{
  "sesm_version": "0.3.0",
  "asset": {
    "id": "apt-caddy-logo",
    "role": "logo",
    "title": "Caddy Web Server Logo",
    "ecosystem": "caddy",
    "tags": ["caddy", "web-server", "logo"]
  },
  "theme": {
    "id": "neon-ink",
    "palette_contract": "nipc-0.1",
    "mode": "dark",
    "tokens": {
      "base": "#0B0F1A",
      "info": "#22D3EE"
    }
  },
  "provenance": {
    "generated": true,
    "generator": {
      "name": "aptlantis-svg-asset-worker",
      "version": "0.2.0",
      "language": "python"
    },
    "generated_at": "2026-05-27T22:21:44Z"
  }
}
]]></metadata>

Key top-level fields:

• asset — describes what the SVG represents (id, role, title, ecosystem, tags). Common roles: logo, icon, theme-board, dataset-card, pipeline-panel, status-badge, decorative, unknown.
• artifact — describes the SVG as a compiled asset in a build pipeline (templates used, source manifests, output paths).
• theme — styling context: modes (dark, light), color contract, accent values, states (running, warning, error, verified), and individual NIPC color tokens.
• ui — hints for UI layout engines (preferred alignment regions, responsive aspect ratio, mouse interactions).
• crawl — directives for indexers and archivers (discoverable API paths, indexing priority).
• llm — natural language explanations, interpretation hints, and cautions intended for LLMs.
• links — canonical links to raw manifests, homepages, licenses, and documentation.
• provenance — audit logs of how the SVG was created (generator tool version, timestamp, git commit).
• integrity — hash value mappings (BLAKE3/SHA-256) connecting the asset to release snapshots.
• extra — vendor namespace for platform-specific extension elements.

Recommended Roles

Common asset.role values: logo, icon, theme-board, dataset-card, dataset-header, pipeline-panel, stats-panel, navigation-card, graph-node, graph-panel, status-badge, download-card, schema-card, archive-summary, landing-hero, page-header, decorative, unknown. Roles should be stable and lowercase, using hyphen-separated names.

Semantic Color Roles

SESM examples may use these NIPC-aligned roles. This list is recommended for Aptlantis Studio, not a universal SESM requirement.

Family	Example Roles	Meaning
Clarity / Orientation	info, structure, navigation, reference, orientation	Understanding, wayfinding, docs
Trust / Validation	success, verified, stable, reproducible, available	Evidence-backed confidence
Attention	important, note, caution, decision, memory-anchor	Pause, notice, remember
Risk / Constraint	critical, error, blocked, constraint, deprecated	Failure, blocker, hard limit
Process / Transformation	process, pipeline, transform, automation, orchestration	Flow, generation, system mechanics
Creation / Build / Code	code-heat, build, operation, artifact-output, tooling	Rust, execution, generated output
Discovery / Creative	featured, creative, discovery, spotlight, human-note	Featured, expressive, exploratory
Research / Experimental	experimental, research, prototype, hypothesis, unstable	Not fully settled yet
Canonical / Archive / Neutral	canonical, archive, muted, unknown, baseline	Definitions, history, quiet metadata

Embedding SESM in SVG

The <metadata> element should use id="sesm", and its contents should be valid JSON text, preferably wrapped in CDATA:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <metadata id="sesm"><![CDATA[
{
  "sesm_version": "0.3.0"
}
  ]]></metadata>

  <circle cx="50" cy="50" r="40" fill="#22D3EE"/>
</svg>

Requirements:

• Only one SESM JSON object should be present per SVG.
• If multiple SESM blocks are present, agents may parse the first and ignore the rest.
• Agents must ignore unknown fields and must not fail because optional fields are missing.

Recommended Validation Rules

A SESM validator should check:

1. SVG contains a <metadata id="sesm"> element.
2. SESM contents parse as valid JSON.
3. sesm_version exists and is a string.
4. Known top-level fields, if present, are objects.
5. URLs, if present, are strings.
6. Colors, if present as hex values, follow #RRGGBB or #RRGGBBAA.
7. asset.role, if present, is a string.
8. crawl.indexable, if present, is boolean.
9. provenance.generated, if present, is boolean.
10. No obvious secret-like fields are present.

Validators should warn, not fail, for unknown fields.

Relationship to JSON-LD and Build Pipelines

SESM complements JSON-LD: HTML pages contain JSON-LD for page-level structured data; SVG files contain SESM for asset-level structured data; SESM links back to canonical HTML and JSON-LD when available.

In Aptlantis Studio, SESM should be produced automatically by the artifact compiler:

JSON/JSONL manifests
  -> Rust generator
  -> SVG templates
  -> compiled SVG artifacts with SESM
  -> static HTML pages
  -> Caddy/static hosting

Reference Tooling

• Embed-SESM.py — embeds and validates SESM metadata in SVG files.
• Validate-SESM-Safe.py — validates SESM metadata and the SESM safe SVG profile.
• Convert-to-SVG.py — converts raster images to SVG (base64 embed or OpenCV vector trace).

See the Tools page for full script listings, the Fixtures page for the validator test corpus, and the SVG Examples gallery for sample assets. Test coverage across embedding, conversion, and safe-profile validation is exercised by the tests/ suite (run_tests.py discovers and runs all test_*.py files); see the tools page for a short coverage summary.

Governance Boundary

SESM governs embedded semantic metadata inside SVG assets, including asset identity, theme context, provenance, UI hints, LLM context, links, and integrity metadata.

SESM does not define the NeonInk palette contract, general visual design style, desktop release packaging, project proposals, or workspace root structure.

SESM may reference NeonInk and NIPC metadata when an SVG asset carries semantic theme information. NeonInk defines the semantic visual language; SESM carries structured metadata about an SVG asset. (NeonInk itself is documented separately; see the NeonInk standard section of City Hall.)