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.

ItemValue
Extension.uky
Media typeapplication/vnd.ukiy+zip
Revision0.18, 28 Oct 2026
Older filesExtension .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.

EntryHoldsRequired
mimetypeThe media type. First entry, stored uncompressedYes
manifest.xmlThe revision, and every part with its type and checksumYes
[Content_Types].xmlThe package’s media types. Not listed in the manifestYes
_rels/.relsThe package’s relationships: the page, and the parts to keep. Not listed in the manifestYes
meta.xmlId, title, author, created, updated, and placement and activity fieldsYes
document/content.xmlThe page: blocks and inline marksYes
document/styles.xmlDocument-level style choicesNo
document/_rels/content.xml.relsThe page’s links to other sheets. A copy for other programs, never readNo
document/crdt.binThe merge state, binary. See Merge stateNo
annotations/comments.xmlText-anchored commentsNo
annotations/notes.xmlPost-itsNo
history/bookmarks.xmlVersions: points in the merge state, with label, time and word countNo
summary/card.xmlThe sheet’s index cardNo
media/<sha256>.pngPictures, named by their contentNo
recovery/Parts a reader could not use, kept byte for byteNo

Manifest

<manifest version="0.18" reader="0.14">
  <part name="document/content.xml" type="content" sha256="…"/>
  <part name="meta.xml" type="meta" sha256="…"/>
</manifest>
AttributeMeaningA reader
versionThe revision the file was written toIs told, and refuses only a missing, non-numeric, zero or negative value
readerThe lowest revision whose writer keeps everything in the fileOpens the file for editing even above its own revision, and says some content may not show or be kept
profileThe app whose subset of the format the file followsOpens an unknown profile for what it understands, and keeps it
minorAn older markerReads 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>
ElementAttributesContains
paraalign, indentText with marks
headinglevel (1, 2, 3, 5), align, indentText with marks
quotealign, indentText with marks
listkind (bullet, number, todo), start, indent, numberingItems
tododoneText with marks. Read always; new to-dos are items of a list of kind todo
codenonePlain text, never marks
tableheader, widths, look, width, alignRows of cells
dividernoneEmpty
imagesrc, alt, align, indent, width, height, cropEmpty

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/>.

ValueAllowed
Block alignmentleft, center, right, justify
Number style1, a, A, i, I
Table lookgridlines, lines, banded, accent, column, outline, plain
Table alignmentleft, center, right
Cell shadegrey, red, orange, gold, green, blue, violet

Marks

Marks wrap text inside a block. They are written in this order, and carry no id.

MarkWritten 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>
ValueAllowed
Colourgrey, red, orange, gold, green, blue, violet
Stylebody, h1, h2, h3, h5
Highlightyellow, orange, pink, violet, blue, green
FontOne 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.

CaseRule
No log in the filecontent.xml is the page, and every block needs an id
A log, and content.xml is what the log last wroteThe log stands
A log, and content.xml was changed by another programcontent.xml is the page, and is folded into the log as an edit
Editing a file with a logCopy 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.

RuleRequirement
Unmodified partsCopy byte for byte. Never parse and rewrite a part you did not change
Unknown partsKeep 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 labelA relationship from the package root, of type http://schemas.openxmlformats.org/package/2006/relationships/mustpreserve, targeting the part
SavingAtomic and never in place: write a temporary file, then rename it over the old one
PathsNormalise every entry path, and refuse any that escapes the extraction root
ChecksumsValidate every CRC-32. Update the manifest’s SHA-256 for any part you change
ZipUTF-8 names. mimetype and media/ stored, XML deflated. Entries under 4 GiB, no zip64
Wrong mimetypeA compressed mimetype gets a warning and still opens. A wrong value is refused
TextNo 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 bytesSame 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.

RevisionReleased
0.1828 Oct 2026
0.1726 Oct 2026
0.1625 Oct 2026
0.1519 Oct 2026
0.1416 Oct 2026
0.1315 Oct 2026
0.1213 Oct 2026
0.1112 Oct 2026
0.1011 Oct 2026