https://
The https:// in the address bar means your information is encrypted and can not be accessed by anyone else
.gov
Only government entities in the U.S. can end in .gov
Digital Standards

File Naming Conventions

File naming conventions for the phila.gov media library

The phila.gov media library holds thousands of files from different City agencies. You can help keep the media library organized by establishing and using well-structured file names.

Consistent, descriptive file names help us all:

  • Find, organize, and replace files.
  • Understand the contents of a file without opening it.
  • Improve digital accessibility.

Best practices for naming files

File naming conventions will vary by type and subject matter, but there are some simple rules you can follow to make them consistent and easy to understand. Arrange the file details in a way that’ll help others sort, search, and understand the contents of a file.

We ask our partners to follow these guidelines for all file names.

Best practice Good example Bad example
Make sure that file names are meaningful and descriptive of their content. ppr-fairmount-park-squirrels.jpg IMAGE_902.jpg
Keep file names short (50 characters or fewer). oit-annual-report-2024.pdf oit-annual-report-and-appendices-a-through-d-with-supplementary-glossary-2024-v04.pdf
Use hyphens (-) to separate each element, not spaces or underscores. oit-meeting-agenda-2024-12-02.pdf oit meeting agenda 2024 12 02.pdf

oit_meeting_agenda_20241202.pdf
Write file names in lowercase, not all caps or camel case. ppr-rec-center-brochure-2024.pdf PPR-REC-CENTER-BROCHURE-2024.pdf

PPR-Rec-Center-Brochure-2024.pdf
Avoid special characters (e.g., / *? “ ” < > ‘ ’ & $). gritty-and-phanatic-parade-float.jpg gritty&phanaticparadefloat.jpg

If you’re not sure whether a file should follow an existing naming convention, check the media library before you upload. You can contact websupport@phila.gov for additional assistance with creating file naming conventions.

Document your naming conventions

To maintain consistency when working within a team or across multiple files, establish a naming convention and document it in a README or internal guide. Keep this documentation with your local files.

Basic format

You can use a basic format like owner-type-date for files with a clear owner (i.e., a department, project, or program):

  1. Owner

Start with the name of the City agency, program, or project that owns the file. Use acronyms and abbreviations to keep it short.

  1. Type

Next, add some keywords to describe the contents of the file.

  • Document title or type
  • Image subject or type
  1. Date

Highlight any relevant dates, such as a meeting, event, or publication date, at the end of the file name. Use the standard date format from the International Organization for Standardization (ISO).

  • Year, month, and day:
    • YYYY-MM-DD; or
    • YYYYMMDD
  • Year and month
    • YYYY-MM
  • Year
    • YYYY

Document translations

Sometimes, you’ll have to upload translated documents to the media library. Documents in a foreign language need to have a language code in their file names. The language code, which comes from the International Organization for Standardization (ISO), represents the language used in the document.

To add a language code, search for the name of the language under the column “ISO 639-1 Code.” Add the two-letter code in lowercase letters to the end of the file name. Jump to see examples.

Versioning

Most public-facing documents are final copies and do not need versioning. You should not use the media library to store different versions of a file for internal use. However, follow these guidelines if you need to track changes over time.

  • Use leading zeros (v01, v02, v03) to help with alignment and sorting.
  • Put the version at the end of the file name and before any language codes, if applicable.

File name examples

Here are some examples of different file names.

Images

  • ppr-jane-smith-headshot
  • ppr-love-park-christmas-village-2025
  • philly-tree-plan-program-image

Flyers

  • ppr-fall-festival-flyer-2025
  • zero-fare-info-session-flyers-2025

Agendas, minutes, and reports

  • complete-streets-monthly-report-2025-10
  • complete-streets-annual-report-2025
  • complete-streets-meeting-agenda-2025-10-10
  • complete-streets-meeting-minutes-2025-10-10

Versioning and language codes

  • Language codes (English, Spanish & Simplified Chinese):
    • revenue-tax-application-2025-en, revenue-tax-application-2025-es, revenue-tax-application-2025-zh
  • Versioning:
    • revenue-tax-form-2025-v01, revenue-tax-form-2025-v02, revenue-tax-form-2025-v03, revenue-tax-form-2025-final

Resources

References Color palette