Name: JSON-LD Validator API: Schema.org Structured Data Check
Brand: glowhalo
SKU: api-glowhalo-json-ld-validator-api
Availability: InStock
Author: API Market

# JSON-LD Structured Data Validator API

## Overview

The JSON-LD Structured Data Validator API checks the schema.org structured data of a web page and returns the result as JSON. The check endpoint takes a page URL, fetches the page, extracts every `<script type="application/ld+json">` block and validates it. The validate endpoint runs the same checks on JSON-LD or HTML you send in the request body, with no outbound request, so you can test markup before it is published. Both endpoints return the same report: the blocks found, the distinct `@type` values, coded issues with a JSONPath-style location, an overall grade from A+ to F, a score out of 100, and a rich-result summary that says, per type, whether its required properties are present.

It is built for developers, SEO teams and content pipelines that need a headless structured data check from CI or a script. Each block is checked for a valid `@context` and `@type`, for required and recommended properties of common Google rich-result types (Article, Product, Offer, LocalBusiness, FAQPage, BreadcrumbList, Event, Recipe, VideoObject, JobPosting and more), and for typical value mistakes such as non-ISO dates, relative URLs and non-numeric prices. Other types get generic checks only. The grade and score use the provider's own formula. A rich-result entry with no missing required properties does not guarantee that Google will show a rich result, and Google's own tools remain the final word. This API is not affiliated with Google or schema.org.

## Features

*   **2 endpoints**: Check the JSON-LD of a live URL, or validate JSON-LD or HTML you supply.
*   **Flexible input**: Check takes a page URL; a value without a scheme, such as `example.com`, is treated as https. Validate takes `jsonld` (an object, an array or JSON text) or `html` (page HTML), up to 256 KB.
*   **Block extraction**: Up to 50 JSON-LD blocks per page, with `@graph` merged and every node validated. The page is fetched once, following up to 5 redirects, and the first 2 MB of HTML is read.
*   **Property rules for common types**: Article, NewsArticle, BlogPosting, LocalBusiness subtypes, Product, Offer, AggregateOffer, AggregateRating, Review, Rating, Organization, Person, WebSite, BreadcrumbList, ListItem, FAQPage, Question, Answer, Event, Recipe, VideoObject, JobPosting and SoftwareApplication.
*   **Coded findings**: Every finding is an `issues[]` entry with a stable `code` (for example `missing_context`, `invalid_date`, `price_not_numeric`, `missing_recommended`), a severity (error, warning or info), a message, a JSONPath-style `path` and the block index.
*   **Grade and score**: An A+ to F grade and a score out of 100 (100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total), plus counts of errors, warnings and infos.
*   **Rich-result summary**: For each rich-result type, `requiredPropertiesPresent` and a `missingRequired` list.
*   **Caching**: Check results are cached for 6 hours per URL; add `fresh=1` to bypass the cache.
*   **Rate limit**: 10 requests per second on both the Free and Basic plans.

## Use Cases

*   **CI and release gates**: Fail a pipeline when a product page loses a required Product or Offer property after a deploy.
*   **SEO audits**: Check a list of URLs and report missing recommended properties and malformed values for each page.
*   **Content pipelines**: Validate generated JSON-LD with the validate endpoint before it is published.
*   **CMS and plugin development**: Test the structured data a template outputs while you build it, without deploying.
*   **Monitoring**: Re-check key pages on a schedule and alert when the grade drops or a rich-result type starts missing required properties.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/glowhalo/json-ld-validator-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate the JSON-LD of a URL

Fetches the page, follows up to 5 redirects, extracts every JSON-LD block and returns the validation report. When the page HTML has no JSON-LD block, `found` is `false` and `grade` is `no_jsonld`. When the page itself answers with HTTP 4xx or 5xx, `found` is `null` and `grade` is `unchecked`. Results are cached for 6 hours per URL, and `cached` tells you whether the report came from the cache.

**Method:** `GET`

**Endpoint:** `/v1/check`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Page to inspect, for example `https://schema.org`. A value without a scheme is treated as https. The aliases `u`, `uri`, `link`, `target`, `site`, `website`, `domain` and `host` are also accepted. | string | Yes | - | - |
| `fresh` | query | Set to `1` to bypass the 6-hour result cache. | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/glowhalo/json-ld-validator-api/v1/check?url=https%3A%2F%2Fschema.org" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged: 3 of 8 issues shown):**

```json
{
  "url": "https://schema.org/",
  "finalUrl": "https://schema.org/",
  "statusCode": 200,
  "cached": false,
  "checkedAt": "2026-10-15T21:51:03.713Z",
  "note": "Only JSON-LD <script> blocks in the served HTML are validated (no JavaScript rendering, no Microdata/RDFa). Property rules cover common Google rich-result types; other types get generic checks. Google's own tools remain the final word on eligibility.",
  "found": true,
  "blockCount": 1,
  "blocks": [
    {
      "index": 0,
      "bytes": 1677,
      "valid": true,
      "types": [
        "WebSite",
        "SearchAction",
        "EntryPoint",
        "Project",
        "Corporation",
        "Organization"
      ],
      "nodes": 9
    }
  ],
  "types": [
    "WebSite",
    "SearchAction",
    "EntryPoint",
    "Project",
    "Corporation",
    "Organization"
  ],
  "richResults": [],
  "grade": "A",
  "score": 95,
  "summary": {
    "errors": 0,
    "warnings": 0,
    "infos": 8
  },
  "issues": [
    {
      "severity": "info",
      "code": "unchecked_type",
      "message": "No property rules exist for @type \"SearchAction\"; only generic checks (dates, URLs, empty values) ran.",
      "path": "$.potentialAction",
      "block": 0
    },
    {
      "severity": "info",
      "code": "missing_recommended",
      "message": "Corporation has no \"logo\" (recommended).",
      "path": "$.about.founder[0]",
      "block": 0
    },
    {
      "severity": "info",
      "code": "missing_recommended",
      "message": "Organization has no \"url\", \"logo\" (recommended).",
      "path": "$.author",
      "block": 0
    }
  ]
}
```

#### 2. Validate JSON-LD or HTML you send in

Runs the same checks on data in the request body, with no outbound request. Send exactly one of `jsonld` or `html`. With `html`, every JSON-LD block in the markup is extracted and validated. The whole request body is limited to 256 KB.

**Method:** `POST`

**Endpoint:** `/v1/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `jsonld` | body | JSON-LD to validate, as an object, an array of objects or JSON text. Send this or `html`, not both. | object, array or string | One of `jsonld` or `html` | - | 256 KB request body |
| `html` | body | Page HTML containing one or more `<script type="application/ld+json">` blocks. Send this or `jsonld`, not both. | string | One of `jsonld` or `html` | - | 256 KB request body |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/glowhalo/json-ld-validator-api/v1/validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonld":{"@context":"https://schema.org","@type":"Product","name":"Trail Shoe","image":"https://example.com/shoe.jpg","offers":{"@type":"Offer","price":"89.00","priceCurrency":"USD","availability":"https://schema.org/InStock"}}}'
```

**Example Response (200 OK):**

```json
{
  "found": true,
  "blockCount": 1,
  "blocks": [
    {
      "index": 0,
      "bytes": 219,
      "valid": true,
      "types": [
        "Product",
        "Offer"
      ],
      "nodes": 2
    }
  ],
  "types": [
    "Product",
    "Offer"
  ],
  "richResults": [
    {
      "type": "Product",
      "count": 1,
      "requiredPropertiesPresent": true,
      "missingRequired": []
    },
    {
      "type": "Offer",
      "count": 1,
      "requiredPropertiesPresent": true,
      "missingRequired": []
    }
  ],
  "grade": "A+",
  "score": 98,
  "summary": {
    "errors": 0,
    "warnings": 0,
    "infos": 2
  },
  "issues": [
    {
      "severity": "info",
      "code": "missing_recommended",
      "message": "Product has no \"description\", \"sku\", \"brand\" (recommended).",
      "path": "$",
      "block": 0
    },
    {
      "severity": "info",
      "code": "missing_recommended",
      "message": "Offer has no \"url\" (recommended).",
      "path": "$.offers",
      "block": 0
    }
  ],
  "checkedAt": "2026-10-15T21:51:05.407Z",
  "note": "Only JSON-LD <script> blocks in the served HTML are validated (no JavaScript rendering, no Microdata/RDFa). Property rules cover common Google rich-result types; other types get generic checks. Google's own tools remain the final word on eligibility."
}
```

### Issue codes

*   **Errors**: `missing_context`, `missing_type`, `empty_jsonld`, `invalid_json`, `no_jsonld`, `missing_acceptedAnswer`, `breadcrumb_too_short` and `missing_<property>` for a missing required property.
*   **Warnings**: `invalid_date`, `relative_url`, `price_not_numeric`, `invalid_currency`, `context_not_schema_org`, `empty_value`.
*   **Infos**: `missing_recommended`, `unchecked_type`, `other_syntaxes_present`, `too_many_blocks`, `date_no_timezone`, `context_http`.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The report is in the response body. For check, the target page's own HTTP status is in `statusCode`, and a page that answers 4xx or 5xx gives grade `unchecked`. |
| 400 | Bad Request | The `url` is missing, invalid, too long, contains credentials, uses an unsupported protocol or points to a private network, or the validate body is invalid (for example `missing_input` when it does not carry exactly one of `jsonld` or `html`, or `too_deep`). The body carries an error code and message. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path does not exist. Check the path against this page. |
| 413 | Payload Too Large | The validate request body is larger than 256 KB (`payload_too_large`). |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan's monthly request quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | Check could not fetch or resolve the target URL (`fetch_failed`, `resolve_failed`). |
| 504 | Gateway Timeout | The target URL did not respond in time (`timeout`). |

## Rate Limits

Both plans allow 10 requests per second: the Free plan (500 requests per month) and the Basic plan (25,000 requests per month). Both quotas are hard limits. Requests above the per-second limit, or after the monthly quota is used up, return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Check results are cached for 6 hours per URL, so repeated checks of the same page within that window return the cached report. Use `fresh=1` only when you need a new fetch, for example right after a deploy.

## FAQ

**Does a clean rich-result entry mean Google will show a rich result?**

No. `requiredPropertiesPresent: true` only means no required-property errors were found for that type. Google decides whether to show a rich result based on other signals too, and its own tools remain the final word.

**How are the grade and score calculated?**

The score is 100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total, with a minimum of 0. The grade comes from the score: A+ 97 and up, A 90, B 80, C 70, D 60, F below 60. This is the provider's own formula, not a Google score.

**What do grade no_jsonld and unchecked mean?**

`no_jsonld` means the served HTML has no JSON-LD block. A bot-challenge page served with HTTP 200 also reads this way. `unchecked` means the page answered with HTTP 4xx or 5xx, which often happens with sites that block datacenter traffic, so nothing could be read.

**Is JSON-LD added by JavaScript detected?**

No. Only JSON-LD present in the HTML the server returns is validated; there is no JavaScript rendering. Microdata and RDFa are detected and reported as an info, but they are not validated.

**How do I check structured data before it is published?**

Send it to `POST /v1/validate`, either as `jsonld` or as the page `html`. No request is made to any site.

**Which types get full property checks?**

Article, NewsArticle, BlogPosting, LocalBusiness and most of its subtypes, Product, Offer, AggregateOffer, AggregateRating, Review, Rating, Organization, Person, WebSite, BreadcrumbList, ListItem, FAQPage, Question, Answer, Event, Recipe, VideoObject, JobPosting and SoftwareApplication. Some of these have recommended-property hints only. Any other type gets the generic checks and an `unchecked_type` info.

**Can I check internal or staging hosts?**

Only if they are reachable from the public internet. Private-network targets are rejected. For anything else, copy the markup and use the validate endpoint.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


JSON-LD validator API that checks the schema.org structured data of a URL or pasted markup and returns coded issues, rich-result checks, a grade and a score.

JSON-LD Validator API: Schema.org Structured Data Check