Writing a docly file to the drive is an import not an edit

Pitfall By design

Writing a .docly file over the mapped drive is a document import, not a field-level edit: it replaces the document rather than patching it. Guid, Schema, the Document payload, EmbeddedFiles and Tags all carry over - tags survive, contrary to what this entry previously claimed. What import does not honour is Created, which the system stamps as the row is written; no API writes it either, so the original date cannot be restored. Where the creation date matters, keep it in a schema field of your own. And do not trust a read of the file you just wrote: the WebDAV redirector can hand back your own source file, envelope and all, which looks like proof that everything round-tripped. Verify from the server with a scratch hash page instead. Measured 2026-09-04: an update pushed with the docly CLI keeps Created untouched - it is neither restamped nor taken from the envelope - so where the creation date matters, editing through the CLI does not have this problem.

Applies to: WebDAV driveSchemasJavaScript

What you'll see

A document you changed one word in comes back missing things you never touched.

The tags are gone. docly.getTags returns an empty array, a tag filter that used to match the document no longer finds it, and the Tags array in the envelope on disk has emptied itself.
Created shows today where it used to show the year the document was written.
You write the old Tags or Created values back into the file, save, read it again — and they are blank once more.

Nothing reports an error. The edit you intended is applied correctly. Only the envelope fields around it are lost.

What's actually happening

Reading and writing a .docly file over the drive are not symmetric operations, and that asymmetry is the whole of this entry.

Reading serializes the document out of the database. The Tags array you see on disk is generated from the document''s tag rows, and Created from its stored creation date.

Writing does not reverse that. The drive parses the file, recognises a valid .docly wrapper and hands it to document import — the same path that brings a document in from outside. Import is a replacement, not a patch. It carries over the identifying Guid, the Schema, the Document payload, the EmbeddedFiles and the Tags.

What import does not honour is Created. That column is set by the system as the row is written. Whatever date sits in the envelope is ignored, and the document is stamped with the moment of import. No API writes it either, so once the original date is gone there is nothing to read it back from.

Verified 2026-08-26. A document was written to the drive with "Tags": ["alfa", "beta", "gamma"] and "Created": "2026-08-26T12:00:00". Reading it back returned the tags as ["beta", "alfa", "gamma"] — reordered, which is only possible if they went through the database''s tag rows rather than being echoed from the file — and Created as the actual import timestamp.

Do not trust the file you just wrote

Immediately after the copy, reading the same path over WebDAV can return your own source file rather than the registered document, because the redirector caches it. In the test above the cached read showed the envelope exactly as written, Created included, and looked like proof that everything round-tripped. It was not.

Verify from the server instead — a scratch .hash page, or a fresh byte-level read once the cache window has passed. See The site drive is WebDAV not a disk and Use a scratch hash file to test Docly functions.

What to do

Tags survive a drive edit. The creation date does not.

Round-tripping a document — read it, change a field, write it back — keeps the tags, because they are in the envelope you read and the envelope you wrote. The one thing to be careful about is a tool that reconstructs the envelope from scratch and omits Tags: what you write is what the document gets, so an omitted array means no tags.

Set tags at creation time by putting them in the envelope:

{
  "Schema": "Invoice",
  "Tags": [ "invoice", "paid" ],
  "Document": { ... },
  "EmbeddedFiles": []
}

docly.addTag remains the way to add a tag to a document that already exists, from an API function, without touching the drive at all.

Where the creation date is content, keep it in a field of your own

A schema field is written by you and never restamped, so it survives any number of drive edits while the envelope''s Created does not:

"Published": "2024-11-03"

Sort and display on that field — the same reasoning as Sort folder contents by a custom field. Trying to repair Created by editing the file does not work: that save is another import, and it stamps the row again.

Verify, do not assume

After writing a .docly file, read it back from the server before believing anything about what registered. The size reported by a directory listing is not a reliable signal either — it can disagree with the content read for the same file, in both directions.

Through the `docly` CLI, the creation date survives

Measured 2026-09-04 against a live site, on a throwaway document created and then updated with the CLI:

On creation the server stamps Created and ignores whatever the envelope says — a file written with "Created": "2019-01-02…" registered with the timestamp of the push. Same behaviour as a drive write.
On update Created was left alone: neither restamped to the moment of the write, nor overwritten by the deliberately wrong 2019 value in the envelope. The Guid was preserved and only Modified moved.
Tags behave the same either way — carried over from the envelope, and returned reordered, which is only possible if they went through the database's tag rows rather than being echoed back from the file.

So the loss of Created is a property of the drive write path, not of writing a whole .docly file. Where the creation date matters and you cannot keep it in a schema field of your own, edit through the CLI. Keeping it in your own field is still the more robust answer, because it does not depend on which route the next person uses.

See How an AI agent should use the docly CLI.