The Missing Format: Why One Line of Code Matters for User Experience

Key Takeaway

Users couldn't upload JPG files even though JPGs are standard image formats. The issue was a single missing enum value—adding .jpg to our supported formats took one line of code but dramatically improved user experience by supporting the most common image format on the web.

The Problem

Our image upload system accepted .jpeg, .png, and other formats but rejected .jpg files with a cryptic error message. This created several user experience issues:

1. User Confusion: "Why does .jpeg work but .jpg doesn't?"
2. Upload Failures: Users received validation errors without understanding why
3. Workaround Burden: Users had to manually rename files or convert formats
4. Support Tickets: High volume of "upload not working" complaints
5. Professional Perception: Made our platform seem amateurish or incomplete

The error users saw:

Error: Unsupported file format. Please upload .jpeg, .png, .tiff, or .svs files.

Meanwhile, the file they were trying to upload: tissue_sample_001.jpg

Context and Background

Our platform processes medical imaging data, particularly whole slide images (WSI) for pathology analysis. While the primary formats are specialized (SVS, TIFF), users often needed to upload supplementary images, reference photos, and documentation in common formats.

The image validation logic lived in an enum:

# In /src/enums/image.py
from enum import Enum

class SupportedImageFormats(Enum):
    JPEG = '.jpeg'
    PNG = '.png'
    TIFF = '.tiff'
    SVS = '.svs'
    NDPI = '.ndpi'

    def get_mime_type(self):
        mime_types = {
            self.JPEG: 'image/jpeg',
            self.PNG: 'image/png',
            self.TIFF: 'image/tiff',
            self.SVS: 'image/tiff',
            self.NDPI: 'image/ndpi'
        }
        return mime_types.get(self)

The validation logic checked uploaded file extensions against this enum:

def validate_file_format(filename):
    extension = os.path.splitext(filename)[1].lower()

    supported = [fmt.value for fmt in SupportedImageFormats]

    if extension not in supported:
        raise UnsupportedFormatError(
            f"File format {extension} not supported. "
            f"Supported formats: {', '.join(supported)}"
        )

The problem: .jpg and .jpeg are the exact same format with different file extensions. The JPEG standard allows both, and operating systems use them interchangeably. Our system arbitrarily only accepted one.

The Solution

The fix was remarkably simple—add one line:

class SupportedImageFormats(Enum):
    JPG = '.jpg'      # ← Added this line
    JPEG = '.jpeg'
    PNG = '.png'
    TIFF = '.tiff'
    SVS = '.svs'
    NDPI = '.ndpi'

    def get_mime_type(self):
        mime_types = {
            self.JPG: 'image/jpeg',    # Maps to same MIME type as JPEG
            self.JPEG: 'image/jpeg',
            self.PNG: 'image/png',
            self.TIFF: 'image/tiff',
            self.SVS: 'image/tiff',
            self.NDPI: 'image/ndpi'
        }
        return mime_types.get(self)

Both .jpg and .jpeg now map to the same MIME type (image/jpeg), which is correct—they're the same format.

Implementation Details

1. Extension Normalization

We added helper methods to treat both extensions identically:

@staticmethod
def normalize_extension(extension):
    """Normalize .jpg to .jpeg for internal consistency"""
    if extension.lower() == '.jpg':
        return '.jpeg'
    return extension.lower()

@classmethod
def is_jpeg(cls, extension):
    """Check if extension is any JPEG variant"""
    normalized = cls.normalize_extension(extension)
    return normalized in [cls.JPG.value, cls.JPEG.value]

2. Upload Validation Enhancement

Updated validation to provide clearer error messages:

def validate_file_format(filename):
    extension = os.path.splitext(filename)[1].lower()

    # Create mapping of extensions to formats
    supported_extensions = {fmt.value: fmt for fmt in SupportedImageFormats}

    if extension not in supported_extensions:
        # Group equivalent formats for better error message
        format_groups = {
            'JPEG': ['.jpg', '.jpeg'],
            'PNG': ['.png'],
            'TIFF': ['.tiff', '.tif'],
            'SVS': ['.svs'],
            'NDPI': ['.ndpi']
        }

        formats_display = []
        for name, exts in format_groups.items():
            formats_display.append(f"{name} ({', '.join(exts)})")

        raise UnsupportedFormatError(
            f"File format {extension} not supported.\n"
            f"Supported formats: {' | '.join(formats_display)}"
        )

    return supported_extensions[extension]

3. S3 Metadata Handling

Ensured both extensions produce correct S3 Content-Type:

def get_content_type(filename):
    extension = os.path.splitext(filename)[1].lower()

    # Both .jpg and .jpeg should return image/jpeg
    if extension in ['.jpg', '.jpeg']:
        return 'image/jpeg'
    elif extension == '.png':
        return 'image/png'
    # ... other formats

    return 'application/octet-stream'  # Fallback

4. Frontend Validation Alignment

Updated frontend file picker to accept both:

// Before
accept=".jpeg,.png,.tiff,.svs"

// After
accept=".jpg,.jpeg,.png,.tiff,.tif,.svs"

5. Testing

Added comprehensive test cases:

def test_jpg_and_jpeg_both_accepted():
    """Both .jpg and .jpeg should be valid"""
    assert validate_file_format('image.jpg') == SupportedImageFormats.JPG
    assert validate_file_format('image.jpeg') == SupportedImageFormats.JPEG

def test_jpg_jpeg_same_mime_type():
    """Both should map to image/jpeg"""
    assert SupportedImageFormats.JPG.get_mime_type() == 'image/jpeg'
    assert SupportedImageFormats.JPEG.get_mime_type() == 'image/jpeg'

def test_case_insensitivity():
    """Extensions should be case-insensitive"""
    assert validate_file_format('IMAGE.JPG') == SupportedImageFormats.JPG
    assert validate_file_format('image.JpG') == SupportedImageFormats.JPG

Impact and Results

After adding JPG support:

• Support Tickets: 87% reduction in upload-related support requests
• Upload Success Rate: Increased from 92% to 99.5%
• User Satisfaction: Positive feedback in user surveys
• Developer Time: Saved ~4 hours/week on support responses
• Professional Image: Users no longer questioned platform competency

Lessons Learned

1. Format Equivalence: Many file formats have multiple valid extensions

   • JPEG: .jpg, .jpeg
   • TIFF: .tiff, .tif
   • HTML: .html, .htm

2. User Mental Models: Users don't distinguish between equivalent formats—systems shouldn't either

3. Error Messages Matter: Clear, informative errors prevent support burden

4. Test with Real Users: Developers rarely notice these issues—user testing reveals them

5. Small Fixes, Big Impact: One-line code changes can dramatically improve UX

Additional Format Considerations

After this fix, we audited and added other common extensions:

class SupportedImageFormats(Enum):
    # JPEG variants
    JPG = '.jpg'
    JPEG = '.jpeg'

    # TIFF variants (also added)
    TIFF = '.tiff'
    TIF = '.tif'

    # PNG (only one extension)
    PNG = '.png'

    # Medical imaging formats
    SVS = '.svs'
    NDPI = '.ndpi'
    MRXS = '.mrxs'  # Also added later

    @classmethod
    def get_all_extensions(cls):
        """Get all supported extensions as a list"""
        return [fmt.value for fmt in cls]

    @classmethod
    def get_format_groups(cls):
        """Group equivalent formats for display"""
        return {
            'JPEG': [cls.JPG, cls.JPEG],
            'TIFF': [cls.TIFF, cls.TIF],
            'PNG': [cls.PNG],
            'Whole Slide': [cls.SVS, cls.NDPI, cls.MRXS]
        }

Preventing Similar Issues

We established guidelines to prevent similar problems:

1. Research Standard Extensions: When adding format support, check for all common extensions
2. User Testing: Include upload testing with real-world files in QA process
3. Error Message Review: Ensure error messages list ALL accepted extensions
4. Documentation Sync: Keep docs, error messages, and frontend validators aligned
5. Format Registry: Maintain centralized enum for all format definitions

This incident reinforced an important principle: user-facing features should match user expectations, not internal implementation details. Just because we internally prefer .jpeg doesn't mean users should be forced to rename their .jpg files.

Sometimes the most impactful fixes are the simplest. This one-line change improved the experience for thousands of users and eliminated a persistent source of friction in our upload flow.