Add Embedded Source Schema (ESS) Support for SVG Output

[ReSearchITEng]

Overview

Implement support for the Embedded Source Schema (ESS) standard in Kroki to embed the original diagram source code directly into generated SVG files as XMP metadata. This makes diagrams self-documenting and immediately editable, very similar to draw.io's abilities where source is embedded.

Problem Statement

Currently, when users generate diagrams using Kroki, the source code used to create the diagram is not retained in the output file (save for exceptions like PlantUML).
Currently users must:

1. Keep the source code in a separate file
2. Re-upload source if they want to edit the diagram
3. Maintain separate versioning for source and rendered assets

Solution

Embed the diagram source as standardized XMP metadata within SVG files using the Embedded Source Schema (ESS) v1.1 specification. This allows:

• Self-contained diagrams: Source is embedded in the output
• Immediate editability: Standard metadata extraction tools can extract and regenerate
• Markdown integration: Works seamlessly with diagram-heavy documentation
• Zero breaking changes: Non-SVG formats and existing API behavior remain unchanged

Implementation Scope (Phase 1)

• Format Support: SVG output only (initial)
• Metadata Standard: XMP/RDF with ESS namespace
• Encoding: gzip+base64 (matches Kroki's existing URL encoding)
• No Infrastructure Changes: Minimal code additions, no new dependencies

Technical Details

The XMP metadata will include:

<metadata>
  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:ess="http://ns.embedded-source.org/1.0/">
    <rdf:Description rdf:about="">
      <ess:Format>mermaid</ess:Format>
      <ess:Payload>H4sIAAAAAAAC/...</ess:Payload>
      <ess:Encoding>gzip+base64</ess:Encoding>
      <ess:Tool>kroki/1.0.0</ess:Tool>
    </rdf:Description>
  </rdf:RDF>
</metadata>

References

• ESS Specification: https://github.com/ReSearchITEng/embedded-source-schema/blob/main/ESS-Kroki-Implementation-Guide.md
• Implementation Plan: https://github.com/ReSearchITEng/embedded-source-schema/blob/main/IMPLEMENTATION_PLAN_SVG.md

Expected Outcome

All SVG diagrams generated by Kroki will automatically include their source code as XMP metadata, making them self-contained, auditable, and immediately editable.

Future Enhancements

• PNG metadata injection (iTXt chunks)
• PDF metadata streams
• Configuration options (enable/disable per endpoint)
• Alternative encoding schemes

---

Labels: enhancement, feature-request

Assignees: None (open for community contribution)

[ggrossetie]

Thanks for the detailed proposal!

A few thoughts:

1. I'd hold off on calling ESS a "standard". The spec linked here (ReSearchITEng/embedded-source-schema) appears to be your own creation and isn't adopted anywhere else yet? That doesn't make the idea bad, just maybe let's not frame it as an established standard in Kroki's docs/code until it has adoption beyond this repo.

2. This should be opt-in, not the default for all SVG output. Maybe via a query parameter or header. Some users won't want their source embedded (output size, or source considered sensitive), so it shouldn't be silent/automatic behavior.

3. Embedding metadata isn't SVG-specific or something to defer to "future enhancements". As far as I know, PNG (tEXt/iTXt chunks) and JPEG (EXIF/XMP) already support arbitrary embedded metadata today (draw.io has been doing this with PNG for years). If we go this route, it'd be worth designing the mechanism with PNG in mind from the start rather than treating it as SVG-only for now.

4. Before designing something new, could you research how draw.io and PlantUML already embed/round-trip source in their output? Kroki already preserves source for PlantUML in some cases, and draw.io's PNG/SVG embedding is widely supported by tooling. Reusing an existing, already-adopted approach would be preferable to introducing a new custom schema.

Happy to discuss further, but I'd want to drop the "standard" framing and make it opt-in before considering implementation.

[ReSearchITEng]

Thank you for your quick reply.
Fully agree with you. The word 'standard' is to be dropped from the docs, it was mainly a way to emphasize that was created to be used beyond kroki, while indeed this was the driver.

there was a deeper research before 'ess', and there is nothing reusable beyond the schema concept which was used.

The idea itself was inspired from draw.io, and initially I was planning to go the same route, but their implementation is specifically draw.io, not something directly reusable.
Also, plantuml was reviewed, as mentioned, I did not look to make a new solution, but it emerged as a need after exausting the other options.

w.r.t. to svg / png / etc - it was intentionally limited in case maintainers (you) would be concerned of too many features at once.

w.r.t. to default true/false : I am ok to default to false, but note, plantuml defaults to yes. As for concerns that someone could copy the diagram code: imo llms do a great job already in reverse engineering a diagram, but I have no hard option, we can default to false.

If there are no other concerning points, I can go ahead with the PR?

[xlsigned]

2. This should be opt-in, not the default for all SVG output. Maybe via a query parameter or header. Some users won't want their source embedded (output size, or source considered sensitive), so it shouldn't be silent/automatic behavior.

👍🏻

I am actually post-processing SVG files generated by plantuml (from kroki) because of plantuml's forced source code embedding. I am using kroki as part of a hugo based rendering pipeline to generate SVG images from diagram sources to be included in the static HTML output.

In this scenario you neither need nor want the diagram source to be embedded in the final SVG. The source that kroki sees might not even be the actual source, because it has been pre-processed, e. g. to include site/document specific styling.

If a general method of embedding the diagram source into the SVG, PNG, ... files generated by kroki is added, I would advocate for making plantuml a "standard" case, i.e. disable unconditional source code embedding there, too.

Anyway, since source code embedding is already a thing in current kroki (for plantuml) I like the idea of generalizing it and making kroki set the "standard".