Tinderbox v9 Icon

Uniqueness, duplicates and matching notes

Does a note (agent, etc.) need to have a unique title ($Name)?

No, though usually unique, an object's title ($Name) is not required to be unique. Same-titled objects will have different a $Path path, unless they are in the same container. Even then, all objects (including aliases) have a discrete $ID enabling duplicate objects to be addressed discretely.

Be aware that generally, most users only employ an object's $Name when making queries or offset code references and this is apparent in most code examples found in the forums and in this resource.

Is is possible to test for duplicated titles?

Yes, by using isDuplicateName(). For instance a stamp with code:

$MyBoolean = isDuplicateName($Name); 

… when applied to one or more objects will set $MyBoolean to true for any object whose $Name is not unique. The scope of the test is always the whole document.

Are there any $Name values to avoid duplicating?

Yes. A number of build-in features—when used—generate root-level containers: prototypes, (export) templates, composites, and hints. It is a good idea to avoid duplicating these features' default containers, indeed all sub-containers within '/Hints'. If it is necessary to duplicate any of these containers (and at root level) ensure the built-in feature generated one is first by outline order ($OutlineOrder).

How do duplicate titles affect queries and finds?

Duplicate-titled notes have no effect on queries which will generate an alias (agent) or path (find()) for each discrete note, even if the duplicate-titled notes are in the same container. It is not documented but it may be because the duplicates are resolved using $ID which will be unique for each. Note that whilst a find() uses a query, like an agent, the difference is that a find() does not weed out matches aliases whereas an agent does so..

How do duplicate titles affect queries and finds?

When using $Name in an offset reference, e.g. $MyString("Some note"), if there is more than one match the resulting action(s) will be carried out only on the first match by outline order ($OutlineOrder). Thus if the $name matches 3 discrete notes, the action will occur three times on the first matched not and not once each on each matched note. This issue can be countered in part by using $Path rather than $Name for the offset reference. If the matches are duplicates within a single container, only $ID can be used to ensure every match note is acted on by the action.


It can be seen that actions—including agent actions—rather than queries that are affected badly by notes with a common name. If document's subject requires the existence of duplicate note titles, extra care should be taken in how actions are addressed to the corrected note(s).

A Tinderbox Reference File : Objects & Concepts : Concepts : Uniqueness, duplicates and matching notes