Image Filenames Descriptive

Issue No: 51

Category: Image Analysis

Issue type: Suggestion

Priority: STANDARD

Description

This audit verifies whether image filenames are descriptive and human-meaningful rather than generic names like img001.jpg. Descriptive filenames improve maintainability and can strengthen image topical context.

How do we capture it

1. Fetch the final page URL and parse raw HTML response.
2. Extract image URLs from <img src>, <img srcset>, and <picture><source srcset> candidates.
3. Normalize each image URL to absolute form and extract pathname filename token.
4. Remove query strings/fragments and decode URL-encoded filename values.
5. Evaluate filename quality rules:
   • descriptive: contains meaningful words/tokens,
   • non-descriptive: generic sequence patterns (for example img001, image1, photo123, random hash-only names where no semantic tokens exist).
6. Capture file extension and base filename separately for diagnostics.
7. Compute page-level ratio of descriptive filenames.
8. Store sample URLs and filename tokens that fail quality rules.
9. Trigger suggestion when non-descriptive filenames exceed thresholds.
10. Persist capture errors for triage when filenames cannot be parsed reliably.

Constraint: The crawler evaluates filename tokens from URL paths only. It does not infer semantic quality from image pixels or surrounding rendered UI.

What to store

Field	Type	Comment
total_images_detected	INT DEFAULT 0	Total image candidates evaluated for filename quality.
descriptive_filenames_count	INT DEFAULT 0	Count of images with descriptive, meaningful filenames.
non_descriptive_filenames_count	INT DEFAULT 0	Count of images with generic/non-meaningful filenames.
descriptive_filename_ratio	DECIMAL(5,2)	Percentage of images using descriptive filenames.
has_non_descriptive_filenames	BOOLEAN DEFAULT FALSE	True when generic filename patterns are detected.
non_descriptive_filename_urls	TEXT[]	Image URLs flagged for filename quality issues.
non_descriptive_filename_tokens	TEXT[]	Filename tokens that matched generic-name patterns.
filename_quality_issue_triggered	BOOLEAN DEFAULT FALSE	Final boolean indicating filename quality issue.
trigger_reason	TEXT	Primary reason code for issue trigger.
capture_error_detail	TEXT	Capture and parsing diagnostics for troubleshooting.

Condition for trigger

Trigger this issue when generic image naming patterns are common enough to affect content clarity.

• Trigger Rule 1: Generic Filename Detected

  • Target Field: filename_quality_issue_triggered
  • Evaluation Logic: non_descriptive_filenames_count > 0
  • Severity: SUGGESTION
  • Diagnostic Message: "Some images use generic filenames. Descriptive naming is recommended."

• Trigger Rule 2: Low Descriptive Filename Ratio

  • Target Field: filename_quality_issue_triggered
  • Evaluation Logic: descriptive_filename_ratio < 70.00 AND total_images_detected >= 5
  • Severity: SUGGESTION
  • Diagnostic Message: "Most image filenames are not descriptive; improve naming quality for clarity and SEO context."

• Trigger Rule 3: Final Issue State

  • Target Field: filename_quality_issue_triggered
  • Evaluation Logic: filename_quality_issue_triggered = TRUE
  • Severity: SUGGESTION
  • Diagnostic Message: "Image filename quality is below best practice and should be improved."

Sources

• Google Search Central: Image SEO best practices: https://developers.google.com/search/docs/appearance/google-images
• Google Search Central: SEO Starter Guide: https://developers.google.com/search/docs/fundamentals/seo-starter-guide
• MDN: URL API and pathname reference: https://developer.mozilla.org/en-US/docs/Web/API/URL

Long description

Descriptive image filenames improve content governance and can provide supplemental semantic hints for image relevance. While filename quality is typically lower impact than alt text or technical performance factors, consistent naming supports scalable asset management and cleaner search indexing signals.

Generic patterns such as img001.jpg or photo_1234.png carry little meaning and can make large media libraries difficult to maintain, audit, and optimize.

Common failure scenarios checked by the crawler:

• Camera-default or CMS-default naming is retained in production.
• Bulk imports preserve opaque IDs as public filenames.
• Build pipelines hash-only filenames without preserving semantic tokens in public URL structure.
• Editorial workflows do not enforce naming standards.

How to Fix

1. Use meaningful, topic-relevant words in image filenames before publishing.
2. Avoid generic numeric naming patterns such as img001 or photo123.
3. Define and enforce media naming standards in CMS/upload workflows.
4. Preserve readable semantic tokens even when cache-busting strategies are used.
5. Re-crawl and validate improved descriptive filename ratio and reduced generic-name samples.