I have no support/technical question and have seen the support category. (Be aware that direct support questions will be deleted.)
on
Which general topic do you have
Hello, I am currently looking for a way to add persistent metadata, e.g. simple strings like “project-y”. Persistent means that the metadata would also be readable with e.g. file explorers, not just in nextcloud itself. I am aware that there was a metadata-api added in version 28. But I am not sure if it only adds metadata on a logical nextcloud level or if the file itself would be altered/the metadata added to the file itself.
Storage of metadata on file level is unfortunately not standarized. E.g. documents (PDF, ODS, DOCX) support it, yet other file types would not support it like markdown, txt files or so.
If I recall correctly, some disk formats might support metadata but it’s again not a uniform given.
The implementation lives in lib/private/FilesMetadata/ in the server repo (introduced in PR #40761 by ArtificialOwl, design spec in Issue #40676). The data is stored in the oc_files_metadata and oc_files_metadata_index database tables — never in the files themselves.
Currently, the API is primarily used for two things:
Extracting metadata from files and indexing it — for example, the Photos app reads EXIF data (GPS coordinates, date taken, image dimensions) from images and writes them into the database so they become searchable and sortable.
Storing computed data that was never in the file — for example, Nextcloud generates a Blurhash for every image (see lib/private/Blurhash/Listener/GenerateBlurhashMetadata.php), which is a compact placeholder string calculated from the image content. This value only exists in the Nextcloud database and has no meaning outside of the Nextcloud UI.
The metadata is accessible via standard WebDAV verbs (PROPFIND to read, PROPPATCH to write, SEARCH to query) under the nc:metadata-* namespace. So in theory, a custom WebDAV client could read and write this data. However, a regular file explorer or a tool like the Windows Explorer will simply ignore these custom WebDAV properties — you would need to build your own client or shell extension to display them, which would be a standalone development project.
Important caveat: Metadata keys need to be registered server-side via IFilesMetadataManager::initMetadata() before they can be written via WebDAV. This means you need at least a minimal Nextcloud app to set things up.
2. The Metadata App by gino0631 (since NC 9)
This is a completely separate community app:
It does something fundamentally different: it reads metadata that is already embedded inside files (EXIF, IPTC, XMP, ID3 tags etc.) and displays it in the Nextcloud sidebar. It is a pure viewer — it does not write anything, neither into the database nor into the files.
Why neither of these solves your problem
Your requirement is metadata that is persistent and portable — readable by file explorers and other tools outside of Nextcloud. Both solutions above keep their data strictly within the Nextcloud ecosystem (one in the database, the other just displays what’s already there).
To achieve what you want, the metadata needs to be written into the files themselves. And here’s the fundamental problem: whether this is possible depends entirely on the file format.
For all of these, tools like ExifTool can read and write custom metadata fields (e.g. an XMP tag with your “project-y” label). Many file explorers, DAM tools (like Adobe Bridge, Lightroom, or Digikam), and media players can display at least some of this natively.
Formats without metadata containers:
Plain text (.txt, .csv, .md, .log)
Source code files
Generic binary formats without a metadata spec
For these, there is simply no standardized place to put metadata inside the file. Your options here would be:
Filesystem extended attributes (xattr on Linux/macOS) — but these are fragile — they get lost when copying between different filesystems, when syncing via the Nextcloud desktop client, or when sharing files via email or public links
Sidecar files — a .xmp or .json file alongside each file. Universally portable but not elegant, and most tools won’t associate them automatically
So what’s the best path forward?
If your files are mostly media or office documents, a script using ExifTool to write XMP metadata (e.g. XMP:Subject = "project-y") directly into the files would be the most robust and portable approach.
If you need it for all file types regardless of format, there is unfortunately no universal solution that survives outside of a specific system. The Nextcloud Metadata API combined with a small custom app could work well within Nextcloud (including via WebDAV), but the moment someone downloads the file or opens it in a regular file explorer, that metadata is gone.