Skip to Content
Structured SchemaIssue 76

No ImageObject schema inside Article or Product

What Is This Issue

ImageObject schema is not embedded within Article or Product schemas that use images. Instead of providing images as plain URL strings, the schema should use full ImageObject blocks with metadata like width, height, caption, and license information.

When images are declared as plain URLs (e.g., "image": "https://example.com/photo.jpg") instead of ImageObject blocks, search engines miss important metadata that could help with:

  • Google Image search rich results
  • AI Overview image citations
  • Better understanding of image context and licensing

A proper ImageObject schema includes: url or contentUrl, width, height, caption, license, and optionally author, datePublished, thumbnail, etc.

Why Is This Important

ImageObject schema enhances image SEO and discoverability:

  • Google Image rich results: Images with proper schema are eligible for badges, captions, and enhanced display
  • AI search citations: AI engines like ChatGPT and Bard use ImageObject metadata to properly attribute and describe images
  • Licensing clarity: license property helps search engines understand image usage rights
  • Accessibility: caption and description improve screen reader experience
  • Dimension information: width and height help browsers reserve space and prevent layout shifts

Resolving this issue improves your overall SEO health score by ensuring images are properly structured for maximum visibility and understanding.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing ImageObject schema:

  1. Detect parent schemas: The crawler identifies pages with Article, Product, Recipe, VideoObject, or NewsArticle schema blocks

  2. Check image property format: For each schema block, the crawler examines the image property:

    • If image is a plain string URL → triggers the issue
    • If image is an array, checks each item in the array
    • If image is already an object with @type: "ImageObject" → validates it has required properties

  3. Validate ImageObject completeness: If ImageObject is present, the crawler checks for:

    • url or contentUrl property
    • width and height properties (recommended)
    • caption property (recommended)

  4. Trigger conditions: The issue is flagged when:

    • A parent schema (Article, Product, etc.) has image as a plain URL string
    • ImageObject exists but is missing url/contentUrl
    • ImageObject exists but is missing width or height (recommendation)

How To Fix

  1. Identify schemas that use images: Check your Article, Product, Recipe, VideoObject, or NewsArticle schema blocks

  2. Replace plain URL strings with ImageObject blocks:

    Before (plain URL):

    {
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Blog Post Title",
  "image": "https://example.com/photo.jpg"
}

    After (ImageObject):

    {
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Blog Post Title",
  "image": {
    "@type": "ImageObject",
    "url": "https://example.com/photo.jpg",
    "width": 1200,
    "height": 630,
    "caption": "Description of the image",
    "license": "https://creativecommons.org/licenses/by/4.0/"
  }
}

  3. Include recommended properties:

    • url or contentUrl (required)
    • width and height in pixels (recommended)
    • caption (recommended for accessibility)
    • license (if applicable)

  4. Validate with Schema Markup Validator

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

FieldTypeDescription
schemaTypeSchemaTypeThe type of schema (e.g., Organization, Person)
schemaFormatSchemaFormatThe format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifierString?Unique identifier for the schema
rawJsonJson?The raw JSON-LD or structured data content
schemaErrorsJson?Array of validation errors found in the schema
isValidSchemaBoolean?Whether the schema is valid according to validation
missingFieldsJson?Array of required fields that are missing

Detection Dependencies

  • The following data sources are required to evaluate this issue:
  • HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
  • Structured Data Validation — The extracted schema is validated against Schema.org definitions
  • Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed

Examples

Example 1: Converting Plain URL to ImageObject in Article

Problematic state (plain URL):

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "SEO Best Practices Guide",
  "image": "https://example.com/images/seo-guide.jpg"
}

Corrected state (ImageObject):

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "SEO Best Practices Guide",
  "image": {
    "@type": "ImageObject",
    "url": "https://example.com/images/seo-guide.jpg",
    "width": 1200,
    "height": 630,
    "caption": "A comprehensive guide to SEO best practices for 2024",
    "license": "https://creativecommons.org/licenses/by/4.0/"
  }
}

Example 2: Multiple Images with ImageObject

Corrected state (multiple images):

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "image": [
    {
      "@type": "ImageObject",
      "url": "https://example.com/headphones-front.jpg",
      "width": 800,
      "height": 800,
      "caption": "Front view of wireless headphones"
    },
    {
      "@type": "ImageObject",
      "url": "https://example.com/headphones-side.jpg",
      "width": 800,
      "height": 800,
      "caption": "Side view of wireless headphones"
    }
  ]
}

Example 3: ImageObject in Recipe Schema

Corrected state (Recipe with ImageObject):

{
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Chocolate Chip Cookies",
  "image": {
    "@type": "ImageObject",
    "url": "https://example.com/cookies.jpg",
    "width": 1200,
    "height": 800,
    "caption": "Freshly baked chocolate chip cookies on a cooling rack"
  }
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-154-imageobject-schema.test.js

Purpose

Validates that the crawler correctly validates ImageObject JSON-LD schemas and does not report false positives when the schema is properly formed.

Tested Function

runStructuredDataRichResults()

Issue Information

  • Issue Number: 154
  • Issue Code: imageobject_schema_embedded
  • Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

  • Valid ImageObject schema: Page has an ImageObject schema with contentUrl and name — no issue reported.

Negative Test Cases

None — the test only validates that valid schemas pass.

Boundary Cases

None.

Edge Cases

  • Empty HTML: <html></html> — no crash.

Expected Outcome

Pass

Issue should not be reported when a valid ImageObject schema with required properties is present.

Fail

No negative test cases are defined.

Validation

  • Correct pass-through of valid ImageObject schemas
  • Graceful handling of empty HTML
  • xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
  • xeopix-crawling-v2/issueCodes.js
  • xeopix-crawling-v2/utils/context.js
  • xeopix-crawling-v2/utils/issues.js
  • xeopix-crawling-v2/utils/schema.js

Coverage Summary

  • Covers valid ImageObject schema detection
  • Covers empty HTML resilience

References

Last updated on
Issue 75Issue 77