Docly Developers
Knowledge base Clarification By design

The nearest schema wins when two schemas share a name

In shortA document finds its schema by name, searching upward from its own folder: the schema on the nearest level wins. Among several schemas with the same name on the same level, the oldest wins (the one created first), so a copy never takes over from the schema that was already there - but a copy placed nearer to the documents does. Docly warns about the ambiguity in the folder view and in the document editor.
Applies to Schemas

  1. What you'll see

    You make a backup copy of a schema, or put a second schema with the same name in another folder, and documents start showing different fields — or you edit a schema and nothing changes, because the documents are bound to another schema with the same name. The folder view or the editor shows a warning that more than one schema has this name.

  2. What's actually happening

    A document stores the name of its schema, not a reference to one document. When it is opened or rendered, Docly resolves the name:

    1. Nearest wins. The search starts in the document's own folder and moves up through the workspace. It stops on the first level that has a schema with that name.
    2. On one level, the oldest wins — the schema document that was created first. A copy made later never takes over the name there, even if it was copied with the original's creation date.

    Two consequences follow. A copy on the same level as the original is harmless for the binding, but it is a trap for whoever edits it. A copy on a level nearer to the documents takes over for every document below it, at once.

    When the binding is ambiguous, Docly says so: the folder view shows a warning when a schema name exists more than once, and the document editor shows which schema was used and which ones were shadowed. Both read the same resolution as the binding itself.

  3. What to do

    • Keep one schema per name in a workspace, normally in #/Schemas/ of the data folder.
    • Do not keep backup copies of a schema in the workspace under the same name. Rename the copy, or keep it outside the workspace.
    • Before you move a schema, check which documents sit below the new and the old location: the move can change which schema they use.
    • When you see the ambiguity warning, delete or rename the extra schema rather than ignoring it. The warning names the schema that won.
    • Renaming a schema is a different problem: documents keep the old name. See Renaming a schema field does not migrate documents for the field-level version.

Last reviewed 17 Oct 2026