The Metadata Beside Your Note: Why a Sidecar File Beats a Hidden Field You Can't Read

A sidecar file is a second file that shares a base name with your note and holds structured metadata the note itself can't carry. It survives copies that strip hidden fields, filesystems that drop extended attributes, and editors that don't know your schema — because it's just a file. Put note.md and note.md.meta.json in the same folder, and any tool that walks the folder gets both.

Sidecars have quietly held photographers' edit histories for two decades. Adobe formalized the pattern in the Extensible Metadata Platform (XMP): "Since early 2012, XMP is also an ISO standard (16684-1)." ¹ Obsidian shipped the same idea into the note world with JSON Canvas — a .canvas file that sits beside your .md and "was created to provide longevity, readability, interoperability, and extensibility to data created with infinite canvas apps." ² The pattern is not fringe. It is what the industries that care most about metadata portability already do. This post is the note-keeper's version of it — one method, one folder convention, and a short list of the mistakes people make when they try to hide the same data somewhere cleverer.

What a sidecar file actually is

A sidecar file is a companion to a source file that carries data the source format can't hold. Wikipedia's definition is the encyclopedic anchor: "Sidecar files, also known as buddy files or connected files, are computer files that store data (often metadata) which is not supported by the format of a source file." ³ The pair shares a base name in one folder and is understood by convention — never by the source format itself.

That last point is what makes the pattern durable. Nothing inside note.md points at note.md.meta.json. Their relationship is the folder. A tool that walks the folder gets both; a tool that opens just the note sees only the note. Neither format has to know about the other, so neither format ever breaks the other.

You already use them. Every RAW photo edited in Lightroom writes an XMP sidecar because RAW files were never designed to hold Lightroom's history stack. DxO PhotoLab writes .dop. Xournal writes .xoj next to a PDF. AmigaOS shipped .info files beside Hunk executables in 1985. ³ The note world's own contribution is JSON Canvas: "JSON Canvas files use the .canvas extension." ² A canvas is a sidecar for the graph of notes it displays.

Why not just put the metadata inside the note?

Because the note is text and some metadata isn't. YAML frontmatter is the right home for a short list of tags, a status, a date — the inline metadata pattern that turns a note into a note that explains itself. But the moment the extra field is a nested JSON tree, a binary blob, or data a second tool owns, frontmatter starts to hurt.

It bloats the file the human reads. It confuses a renderer that expected front matter to be short. And it forces the second tool to parse markdown just to reach its own data. A sidecar keeps the two concerns apart: the note stays a note, the extra data stays legibly structured, and both are grep-able with the same command.

Why not use an extended attribute (xattr)?

Because xattrs disappear the moment a copy leaves the system that made them. The Linux xattr(7) manpage defines them as "name:value pairs associated permanently with files and directories, similar to the environment strings associated with a process." ⁴ That analogy is the whole problem — environment strings live inside a process; xattrs live inside a filesystem. Move the file to a filesystem that doesn't know the shape, and the shape is gone.

The size ceiling is small on purpose: "The VFS-imposed limits on attribute names and values are 255 bytes and 64 kB, respectively." ⁴ That's fine for a colour tag, hopeless for a JSON tree.

Copy semantics are worse. The Arch Linux Wiki lists the exact opt-in flags: rsync requires -X, --xattrs to preserve them at all, and tar needs --xattrs for creation and --xattrs-include='*' for extraction. ⁵ Miss the flag on either end of the round-trip and the metadata is silently stripped. Practitioner authority Richard Maw, writing on the Yakking blog about the mechanics of copying files with metadata, warns: "some have rather awkward interfaces as far as copying is concerned, some because they don't depend on the file's contents itself, and some because they are filesystem specific." ⁶

Then there's the destination-filesystem problem. Wikipedia's article on Extended file attributes lists the Linux filesystems that support them: "ext2, ext3, ext4, JFS, Squashfs, UBIFS, Yaffs2, ReiserFS, Reiser4, XFS, Btrfs, OrangeFS, Lustre, OCFS2 1.6, ZFS, and F2FS filesystems support extended attributes." ⁷ Notice what isn't on the list: the format on almost every USB stick sold in the last twenty years.

On FAT32, xattrs cannot be stored at all — the two bytes OS/2 used for the purpose are already reserved: "These two bytes are used for other purposes on the FAT32 filesystem, and hence OS/2 extended attributes cannot be stored on this filesystem." ⁷ Copy your notes to a thumb drive, open them on a friend's laptop, and every xattr you set is gone. The file looks fine. The rating you spent an evening tagging into the metadata is not.

Where the sidecar pattern comes from — and what earns your trust

Adobe's XMP is the industry-scale precedent. Their developer docs describe it as "a file labeling technology that lets you embed metadata into files themselves during the content creation process," and note that "Since early 2012, XMP is also an ISO standard (16684-1)." ¹ Twenty years of photographers editing millions of RAW files trust that pattern.

Wikipedia's sidecar entry spells out the operational rule the photography industry follows: "Extensible Metadata Platform (XMP) metadata is stored in a sidecar file when either a file format does not support embedded XMP metadata or if the workflow requires this." ³ That is exactly the choice a note-keeper faces when a JSON tree, a binary blob, or a second tool's data won't fit inside the note.

Obsidian's JSON Canvas is the closest note-world sibling. Its landing page is the whole pitch: "The format is designed to be easy to parse and give users ownership over their data. JSON Canvas files use the .canvas extension." ² The parallel to Steph Ango's philosophy is deliberate: "Apps are ephemeral, but your files have a chance to last." ⁸ A canvas is a .md-sibling that a competitor's editor can still read tomorrow.

The four-step method

The whole discipline is four decisions you make once and enforce with a naming rule.

Step 1 — Decide the sidecar's extension by shape. Use note.md.meta.json for structured trees, note.md.yml for lists a human might edit, note.md.tasks.json for a second tool's own data. The convention that matters is <same-base-name-as-the-note>.<second-extension> — same base name, one folder. Adobe's .xmp, Obsidian's .canvas, DxO's .dop, Xournal's .xoj all follow that shape. ³

Step 2 — Shape the schema you own. Write the sidecar's schema down in a README beside your vault. Which fields exist. What each field means. What happens to a field a tool doesn't recognise (the answer should always be "leave it alone"). If you can't describe the shape in a paragraph, the shape is wrong.

Step 3 — Name it so grep, tar, and git don't hate you. Two files, one base name, differ only in the second extension. That is deliberate. grep -r "rating" notes/ walks both. tar cf notes.tar notes/ includes both. git status shows both. No hidden field, no filesystem-specific attribute, no database — every UNIX tool written in the last fifty years already knows how to work with a text file next to another text file.

Step 4 — Link back by convention, not by pointer. The sidecar does not reference the note. The note does not reference the sidecar. They share a base name, and a two-line loader in whatever tool consumes them looks for a same-name sibling. Break the base-name pair only at rename time — see the honest limit below.

Concretely, a note plus its sidecar looks like this:

notes/
  2026-07-02-sidecar-files-are-metadata.md
  2026-07-02-sidecar-files-are-metadata.md.meta.json

{
  "schema": "note-meta/1",
  "review_state": "in-progress",
  "reading_time_seconds": 720,
  "sources": [
    { "type": "manpage", "id": "xattr(7)", "url": "https://man7.org/linux/man-pages/man7/xattr.7.html" },
    { "type": "spec", "id": "XMP / ISO 16684-1", "url": "https://developer.adobe.com/xmp/" }
  ],
  "extras": {
    "internal_priority": 3,
    "revisit_after": "2026-08-01"
  }
}

Nothing in that JSON file needs to be understood by the markdown renderer, and nothing in the markdown file needs to be understood by the JSON reader. That is the point. Each tool sees only what it was built to see, and both see plain text.

Common mistakes

Mistake 1 — Using xattrs because "it works on my Mac." APFS supports them. So does ext4. So does NTFS. But xattr(7) names four attribute classes — security, system, trusted, and user — and only user.* is portable at all; the manpage warns that "Additional classes may be added in the future." ⁴ Even inside the user namespace, the size limit (255 bytes for the name, 64 kB for the value) ⁴ rules out anything bigger than a colour tag. And unless every tool you'll ever copy your notes with passes -X / --xattrs, the attribute is silently dropped. Sidecar files ship with the file.

Mistake 2 — Assuming the copy tool preserves your extras. It doesn't. ArchWiki's Extended-attributes reference names the flags: rsync requires -X, --xattrs; tar requires --xattrs for creation and --xattrs-include='*' for extraction. ⁵ Standard cp on many systems needs --preserve=xattr or -a. Miss one of these on one side of a round-trip and the data is gone. There is no warning. A sidecar's copy semantics are the copy semantics of any other file.

Mistake 3 — Stuffing a JSON tree into YAML frontmatter to avoid a second file. Frontmatter is a header, not a container. A 400-line JSON blob inside a --- fence bloats the note the human reads, breaks renderers that expected a short block, and forces every tool to parse markdown to reach its own data. The rule of thumb: if the structured data is bigger than the note's own text, the data belongs in a sidecar. Frontmatter is the inline pattern for short, text-shaped metadata; the sidecar is the external pattern for everything else.

Mistake 4 — Trusting the file manager to keep the pair together. This is the real, honest limit of the sidecar pattern, and Wikipedia says it plainly: "The problem with this system is that most operating systems and file managers have no knowledge of these relationships, and might allow the user to rename or move one of the files thereby breaking the relationship." ³ The pattern is not magic. If you rename note.md and forget to rename note.md.meta.json, the pair is broken. The fix is discipline: rename with a script that walks both, or use a file manager that groups them. The sidecar pattern's inventors are honest about this limit; so are we.

Mistake 5 — Reaching for a vendor database because it "feels tidier." A Notion column is not portable. A Bear plist is not grep-able. An Evernote SQLite blob is decoded by exactly one program. When that program goes away, the data doesn't go away with it — the access to the data goes away with it. A sidecar is a text file next to another text file. Every tool understands how to leave a text file alone.

How this works in a MNMNOTE-shaped vault

MNMNOTE stores notes as plain markdown files on your own device. A sidecar sits in the same folder as its note: note.md is a note any editor can open, and note.md.meta.json (or .yml, or .tasks.json) is a sidecar any editor can open. Nothing inside the app owns the sidecar; nothing outside the app is blocked from reading it.

You can back the pair up, diff it, tar it, git it, and grep it with the same tools you already use — same as the note itself. That symmetry is the whole design goal: the extra data is a first-class file, not a hidden field inside one app's storage.

Frequently asked questions

Q: How difficult is it to preserve extended attributes when moving a file? Harder than it looks. Default cp, tar, and rsync drop xattrs unless you pass the right flag: the Arch Linux Wiki's copy-tool table lists rsync as -X, --xattrs and tar as --xattrs for creation and --xattrs-include='*' for extraction. ⁵ Copy to FAT32/exFAT (most USB drives) and the xattrs cannot be stored at all — "these two bytes are used for other purposes on the FAT32 filesystem, and hence OS/2 extended attributes cannot be stored on this filesystem." ⁷ A sidecar file has none of these gotchas because it is just another file.

Q: How do I add metadata to a markdown file? Two patterns, one decision. If the metadata is short, text-shaped, and belongs inside the note (tags, status, publish date), use YAML frontmatter. If it's a JSON tree, a table of review states, binary-shaped data, or data a second tool owns, put it in a sidecar file next to the note (note.md plus note.md.meta.json). Frontmatter is the inline pattern; the sidecar is the external one.

Q: What is a sidecar file? A companion file that shares a base name with a source file and holds metadata the source format can't carry. Wikipedia's lede is the canonical definition: "Sidecar files, also known as buddy files or connected files, are computer files that store data (often metadata) which is not supported by the format of a source file." ³ Examples in the wild: XMP for photos, .dop for DxO PhotoLab, .xoj for Xournal, .canvas for JSON Canvas in Obsidian.

Q: Why do XMP sidecars exist? Because RAW image formats can't hold the edit history Adobe wants to record. Wikipedia's rule: "Extensible Metadata Platform (XMP) metadata is stored in a sidecar file when either a file format does not support embedded XMP metadata or if the workflow requires this." ³ Adobe's docs describe XMP as "a file labeling technology that lets you embed metadata into files themselves during the content creation process," now ISO-standardized as 16684-1. ¹

Q: Does tar preserve extended attributes by default? No. The ArchWiki Extended-attributes reference is explicit: tar needs --xattrs for creation and --xattrs-include='*' for extraction to preserve xattrs on both sides of the round-trip. ⁵ Miss either flag and the attributes are silently stripped. This is the copy-mechanics reason sidecars beat xattrs for anything you want to keep.

Q: Do extended attributes survive when I copy a note to a USB drive? Usually not. Most USB drives ship formatted FAT32 or exFAT. FAT32 cannot store extended attributes at all — the bytes are already used for other purposes. ⁷ Even copying to a drive that could store them requires opt-in flags on cp/tar/rsync (see the previous FAQ). A sidecar file survives the copy because it's a normal file.

Q: How do I attach a JSON blob to a markdown note? Write the JSON to a sibling file with the same base name — for a note called 2026-07-02-review.md, write 2026-07-02-review.md.meta.json in the same folder. Any tool that walks the folder gets both, and neither format has to know about the other. This is the sidecar pattern, and it is what Obsidian's JSON Canvas does at the graph level: a .canvas file next to .md files.

The one line to remember

Files outlast apps because they don't need permission to be read. That is Steph Ango's whole point in File over app — a philosophy: "if you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read. Use tools that give you this freedom." ⁸

A hidden field is not that. A filesystem attribute that vanishes on a USB copy is not that. A sidecar file, sharing a base name with your note in a folder both of you can read, is exactly that.

If this resonates, mnmnote.com is a browser-based markdown editor built by enthusiasts — notes and any sidecars you keep beside them stay in plain files on your own device, in a folder any editor can walk.