The .uky format
Revision 0.18, 28 Oct 2026.
Summary
.uky is an open format. A .uky file is a zip of XML parts, and a standard package under the Open Packaging Conventions (OPC), ECMA-376 Part 2. This page outlines revision 0.18.
| Item | Value |
|---|---|
| Extension | .uky |
| Media type | application/vnd.ukiy+zip |
| Revision | 0.18, 28 Oct 2026 |
| Older files | Extension .ink and media type application/ink+zip are read, never written |
Parts
The first six entries are the smallest file. A reader that meets a part it does not know follows the rules.
| Entry | Holds | Required |
|---|---|---|
mimetype | The media type. First entry, stored uncompressed | Yes |
manifest.xml | The revision, and every part with its type and checksum | Yes |
[Content_Types].xml | The package’s media types. Not listed in the manifest | Yes |
_rels/.rels | The package’s relationships: the page, and the parts to keep. Not listed in the manifest | Yes |
meta.xml | Id, title, author, created, updated, and placement and activity fields | Yes |
document/content.xml | The page: blocks and inline marks | Yes |
document/styles.xml | Document-level style choices | No |
document/_rels/content.xml.rels | The page’s links to other sheets. A copy for other programs, never read | No |
document/crdt.bin | The merge state, binary. See Merge state | No |
annotations/comments.xml | Text-anchored comments | No |
annotations/notes.xml | Post-its | No |
history/bookmarks.xml | Versions: points in the merge state, with label, time and word count | No |
summary/card.xml | The sheet’s index card | No |
media/<sha256>.png | Pictures, named by their content | No |
recovery/ | Parts a reader could not use, kept byte for byte | No |
Manifest
<manifest version="0.18" reader="0.14"> <part name="document/content.xml" type="content" sha256="…"/> <part name="meta.xml" type="meta" sha256="…"/> </manifest>
| Attribute | Meaning | A reader |
|---|---|---|
version | The revision the file was written to | Is told, and refuses only a missing, non-numeric, zero or negative value |
reader | The lowest revision whose writer keeps everything in the file | Opens the file for editing even above its own revision, and says some content may not show or be kept |
profile | The app whose subset of the format the file follows | Opens an unknown profile for what it understands, and keeps it |
minor | An older marker | Reads it. No writer writes it from 0.14 |
Page
document/content.xml is a list of blocks under <content version="1">. Every block carries an id: four characters of a-z and 0-9, unique in the page.
<content version="1">
<heading id="b7k2" level="2">File bar</heading>
<list id="c4mq" kind="bullet">
<item id="d81f">First</item>
<item id="e0zt"/>
</list>
<para id="j5wd">Plain text with <b>bold</b>.</para>
<table id="k2vn" header="true">
<row id="m3xa"><cell id="n9qe">Name</cell><cell id="p1rf">Age</cell></row>
</table>
</content>| Element | Attributes | Contains |
|---|---|---|
para | align, indent | Text with marks |
heading | level (1, 2, 3, 5), align, indent | Text with marks |
quote | align, indent | Text with marks |
list | kind (bullet, number, todo), start, indent, numbering | Items |
todo | done | Text with marks. Read always; new to-dos are items of a list of kind todo |
code | none | Plain text, never marks |
table | header, widths, look, width, align | Rows of cells |
divider | none | Empty |
image | src, alt, align, indent, width, height, crop | Empty |
A list item holds text with marks, then at most one nested list, four levels deep at most. A to-do item carries done. A cell may carry colspan, rowspan, shade and align. A hard break in text is <br/>.
| Value | Allowed |
|---|---|
| Block alignment | left, center, right, justify |
| Number style | 1, a, A, i, I |
| Table look | gridlines, lines, banded, accent, column, outline, plain |
| Table alignment | left, center, right |
| Cell shade | grey, red, orange, gold, green, blue, violet |
Marks
Marks wrap text inside a block. They are written in this order, and carry no id.
| Mark | Written as |
|---|---|
| Bold, italic | <b>, <i> |
| Underline, strikethrough | <u>, <s> |
| Colour, font, style, highlight | <mark colour="…" font="…" style="…" highlight="…">, each only when set |
| Link, link to a sheet | <a href="…">, <a note="…">. With neither, read as plain text |
| Code | <code> |
| Value | Allowed |
|---|---|
| Colour | grey, red, orange, gold, green, blue, violet |
| Style | body, h1, h2, h3, h5 |
| Highlight | yellow, orange, pink, violet, blue, green |
| Font | One of 45 named fonts ShowInter, Hanken Grotesk, DM Sans, Source Sans 3, Figtree, Work Sans, Mulish, Cabin, Poppins, Nunito, Quicksand, Space Grotesk, Atkinson Hyperlegible, IBM Plex Sans, Roboto, Lexend, Open Sans, Lato, OpenDyslexic, Lora, EB Garamond, Source Serif 4, Literata, Crimson Pro, Spectral, Newsreader, Merriweather, Libre Baskerville, Cormorant Garamond, Petrona, Libre Caslon Text, Zilla Slab, Bitter, Roboto Slab, JetBrains Mono, IBM Plex Mono, Source Code Pro, Space Mono, Courier Prime, Azeret Mono, Caveat, Kalam, Patrick Hand, Shadows Into Light Two, Special Elite |
Merge state
document/crdt.bin holds a conflict-free replicated data type (CRDT) log, so copies of a file can merge. This outline does not define its encoding. You can write a correct file without it.
| Case | Rule |
|---|---|
| No log in the file | content.xml is the page, and every block needs an id |
A log, and content.xml is what the log last wrote | The log stands |
A log, and content.xml was changed by another program | content.xml is the page, and is folded into the log as an edit |
| Editing a file with a log | Copy the log as it is, and leave contentSha in meta.xml alone. Give a new block no id: the log holds ids the page does not show |
Rules
What every reader and writer must do, and two things Kozo does that we advise.
| Rule | Requirement |
|---|---|
| Unmodified parts | Copy byte for byte. Never parse and rewrite a part you did not change |
| Unknown parts | Keep a part you do not understand when _rels/.rels labels it must-keep, or when the file is older than revision 0.14 and has no labels. Label every unknown part you write |
| Must-keep label | A relationship from the package root, of type http://schemas.openxmlformats.org/package/2006/relationships/mustpreserve, targeting the part |
| Saving | Atomic and never in place: write a temporary file, then rename it over the old one |
| Paths | Normalise every entry path, and refuse any that escapes the extraction root |
| Checksums | Validate every CRC-32. Update the manifest’s SHA-256 for any part you change |
| Zip | UTF-8 names. mimetype and media/ stored, XML deflated. Entries under 4 GiB, no zip64 |
| Wrong mimetype | A compressed mimetype gets a warning and still opens. A wrong value is refused |
| Text | No character XML 1.0 cannot carry. CR, VT and FF become a line feed; other C0 controls become their Control Pictures; U+FFFE, U+FFFF and lone surrogates become U+FFFD |
| Links (advised) | Do not follow a link whose address is javascript:, data: or vbscript: |
| Read limits (advised) | 20,000 entries, 512 MiB a part, 1 GiB in all, and a compression ratio of 200 above 4 MiB |
| Canonical bytes | Same content, same file: fixed attribute order with id first, LF, parts sorted by name, fixed zip timestamps |
Revisions
The revision moves by 0.01 with each release that changes the format. It stays below 1.0 while the format is being settled.
| Revision | Released |
|---|---|
| 0.18 | 28 Oct 2026 |
| 0.17 | 26 Oct 2026 |
| 0.16 | 25 Oct 2026 |
| 0.15 | 19 Oct 2026 |
| 0.14 | 16 Oct 2026 |
| 0.13 | 15 Oct 2026 |
| 0.12 | 13 Oct 2026 |
| 0.11 | 12 Oct 2026 |
| 0.10 | 11 Oct 2026 |