Overview

When ValidGraph detects missing or incorrect properties, it generates ready-to-use JSON-LD code snippets that fix the issues. Users can copy and paste the suggestions directly into their markup to improve their schema completeness score and rich snippet eligibility.

How It Works

1. Validation identifies missing/incorrect properties
2. For each issue, ValidGraph generates a fix suggestion:
– The property name and expected type
– A JSON-LD code example with placeholder values
– Context on why the property matters (SEO impact)
3. Suggestions are prioritized by impact (required > recommended > optional)

Tier Availability

| Tier | Available |
|——|———–|
| Free | No |
| Pro | Yes |
| Agency | Yes |
| Enterprise | Yes |

Related Features

– Schema Completeness Score: Suggestions target score improvement
– Rich Snippet Eligibility: Fixes focus on rich results requirements

Quick Start: Get and Apply Fix Suggestions

Step 1: Validate your markup (via URL or paste)

Step 2: Review “Fix Suggestions” section in results
Each suggestion includes:
– Missing/incorrect property name
– Suggested JSON-LD code block
– Why it matters (SEO/rich snippet impact)
– Estimated score improvement

Step 3: Copy suggested code into your page’s or existing JSON-LD block

Step 4: Re-validate to confirm score improvement

Example workflow:
Your Article scores 62. Suggestions:
1. Add image property (+4 points)
2. Add publisher property (+2 points)
3. Add dateModified property (+2 points)

Apply all three → Re-validate → New score: 80 (10.9% improvement)

Technical Details

Suggestion Generation

When validation detects missing/incorrect properties, the FixSuggestions engine generates actionable fixes:

1. Identify gaps: Compare detected properties against required/recommended sets
2. Generate examples: Create JSON-LD snippet with placeholder values
3. Calculate impact: Estimate score improvement if property is added
4. Prioritize: Rank by weight (required > recommended > optional) and impact
5. Explain context: Include why the property matters for SEO

Request/Response Format

Request (validation with Pro+ tier):

{
  "data_url": "https://example.com/article"
}

Response (includes fix_suggestions):

{
  "success": true,
  "data": {
    "url": "https://example.com/article",
    "validation_id": "val_article_456",
    "score": 62,
    "types": ["Article"],
    "fix_suggestions": [
      {
        "rank": 1,
        "priority": "high",
        "property": "image",
        "weight_category": "recommended",
        "current_status": "missing",
        "impact": {
          "score_improvement": 4,
          "new_score_if_added": 66,
          "rich_snippet_impact": "Images appear in rich results and improve CTR"
        },
        "suggested_code": {
          "format": "json_ld",
          "snippet": ""image": "https://example.com/image.jpg""
        },
        "implementation_note": "Can be a string URL or an ImageObject with url, width, height",
        "example_values": [
          "https://example.com/images/article-hero.jpg",
          {"@type": "ImageObject", "url": "https://example.com/image.jpg", "width": 1200, "height": 630}
        ]
      },
      {
        "rank": 2,
        "priority": "high",
        "property": "dateModified",
        "weight_category": "recommended",
        "current_status": "missing",
        "impact": {
          "score_improvement": 2,
          "new_score_if_added": 68,
          "rich_snippet_impact": "Signals content freshness to Google; recent updates more likely to rank"
        },
        "suggested_code": {
          "format": "json_ld",
          "snippet": ""dateModified": "2024-03-20T10:30:00Z""
        },
        "implementation_note": "ISO 8601 format. Use current date if not tracking modification date",
        "example_values": [
          "2024-03-20T10:30:00Z",
          "2024-03-20"
        ]
      },
      {
        "rank": 3,
        "priority": "medium",
        "property": "publisher",
        "weight_category": "recommended",
        "current_status": "missing",
        "impact": {
          "score_improvement": 2,
          "new_score_if_added": 70,
          "rich_snippet_impact": "Helps establish publisher authority"
        },
        "suggested_code": {
          "format": "json_ld",
          "snippet": ""publisher": {"@type": "Organization", "name": "Your Site Name", "logo": {"@type": "ImageObject", "url": "https://example.com/logo.png"}}"
        },
        "implementation_note": "Can be Organization type with name and optional logo",
        "example_values": [
          "{"@type": "Organization", "name": "My Publication"}",
          "{"@type": "Organization", "name": "My Publication", "logo": {"@type": "ImageObject", "url": "https://example.com/logo.png", "width": 500, "height": 500}}"
        ]
      }
    ],
    "errors": [],
    "warnings": [
      {"property": "image", "message": "Recommended property missing"}
    ]
  }
}

Correction Suggestions (for Invalid Values)

When a property exists but has an invalid value, suggestions include correction options:

{
  "fix_suggestions": [
    {
      "property": "datePublished",
      "weight_category": "required",
      "current_status": "incorrect",
      "current_value": "03/15/2024",
      "error": "Invalid date format. Expected ISO 8601 (YYYY-MM-DD or RFC 3339)",
      "suggested_code": {
        "format": "json_ld",
        "snippet": ""datePublished": "2024-03-15T00:00:00Z""
      },
      "correction_options": [
        "2024-03-15",
        "2024-03-15T12:00:00Z",
        "2024-03-15T12:00:00-05:00"
      ],
      "impact": {
        "score_improvement": 0,
        "note": "Fixes existing property; doesn't add new value but validates current one"
      }
    }
  ]
}

Suggestion Prioritization Rules

Suggestions are ranked by:
1. Weight: Required properties before recommended before optional
2. Impact: Higher score improvement first
3. Difficulty: Easier implementations first (string fields vs complex objects)

Batch Suggestion Generation

For bulk CSV validation, suggestions aggregate across all URLs:

{
  "aggregate_suggestions": {
    "most_common_missing_properties": [
      {"property": "image", "missing_in_urls": 23, "avg_impact": 4.2},
      {"property": "dateModified", "missing_in_urls": 18, "avg_impact": 2.1},
      {"property": "description", "missing_in_urls": 15, "avg_impact": 2.0}
    ],
    "total_score_improvement_potential": 85,
    "average_score_after_fixes": 87.3
  }
}

References

– Schema.org Property Documentation: https://schema.org/docs/documents.html
– Article Schema Specification: https://schema.org/Article
– ISO 8601 Date Format: https://en.wikipedia.org/wiki/ISO_8601
– Google Rich Results Checklist: https://developers.google.com/search/docs/appearance/structured-data/article
– JSON-LD Implementation Guide: https://json-ld.org/learn