A file-naming system is reliable only when people can apply it consistently without guessing. The document behind the system should explain why each component exists, which files it covers, who owns the vocabulary, and how a change will be introduced without breaking links or creating duplicate versions. A list of example names is helpful, but it is not enough by itself.
Define purpose and scope
Start with the decision the name must support. Common needs include chronological sorting, project grouping, record identification, version control, privacy, or transfer between systems. State which repositories, teams, file types, and lifecycle stages are in scope. Exclude temporary downloads, application-managed package files, or regulated records if they follow another rule.
Name the policy owner, repository owner, vocabulary steward, and migration approver. A shared drive may have one technical owner while a program manager controls project codes. Record who can create a new code, retire one, approve an exception, or change the pattern. Add an effective date and review date.
The U.S. National Archives' file and folder naming guidance advises federal agencies to use descriptive, consistent, meaningful conventions and to keep components such as project names, dates, and versions in the same positions. It also warns that file systems differ in supported path lengths and characters. Although the specific rules are written for federal records, the underlying need for predictable, portable names applies broadly.
Write the pattern as fields
Describe the name as ordered fields rather than prose. For example: project code, document type, subject, date, version, status, and extension. For each field, specify allowed values, length, capitalization, separator, whether it is required, and who owns its vocabulary. Define one date format and say whether the date is creation, event, approval, or publication date.
Give valid and invalid examples with explanations. Include leading zeros for numbered sequences if lexical sorting matters. Reserve the period before the file extension and define whether hyphens or underscores separate words and fields. Avoid labels such as final, latest, new, or copy unless the policy gives them a controlled meaning.
NARA's file-naming best practices recommends unique, consistently structured names, persistent elements, standard date notation, file extensions, and simple cross-platform characters. It also cautions against overlong, complex schemes that invite manual error. Use those recommendations as design inputs, then test the result in the actual systems your team uses.
Separate names from metadata
Decide which facts belong in the filename and which belong in repository metadata. A file name should remain readable and portable, but it cannot safely carry every owner, retention category, access restriction, approval, and descriptive keyword. Record the system fields that hold those facts and what happens when a file leaves that system.
Do not put customer names, health information, payment data, passwords, internal case details, or unnecessary personal identifiers in filenames. Names often appear in search results, logs, synchronization notices, links, backups, and email attachments. Document a safe placeholder or protected identifier for sensitive cases.
Define versions, status, and collisions
Choose whether the repository, the filename, or both control versions. If versions appear in names, define the format, increment owner, and relationship between draft, review, approved, and superseded states. Explain whether an approved file may be renamed and how references are updated.
State what happens when two files would receive the same name. Do not let users invent ad hoc suffixes silently. Use a controlled sequence, unique record ID, or repository collision process. Document case sensitivity and Unicode behavior if files move across Windows, macOS, Linux, cloud storage, or external systems.
Plan migration and change control
Test the convention on a representative sample before renaming a library. Measure full path length, sorting, searchability, links, synchronization, scripts, and external references. Keep a mapping from old to new names and use a recoverable staged migration. Never bulk rename active records without an authorized rollback plan.
Record every policy change with reason, approver, affected scope, compatibility impact, examples, migration decision, and effective date. The naming system is ready when a new user can name and find representative files, exceptions are explicit, sensitive data stays out of names, collisions have a rule, and one owner is accountable for the vocabulary.
Sources
- Bulletin 2015-01 Appendix B — U.S. National Archives and Records Administration
- Best Practices for File Naming — U.S. National Archives and Records Administration, Aug. 22, 2017