# Content QA: One Pass for JSON-LD, FAQ and raw-md


# Content QA: One Pass for JSON-LD, FAQ and raw-md

## What this helps you with

Before publishing you cannot tell whether the content is right: is JSON-LD complete, does FAQ match the page, can AI read the raw-md?
Content QA is a pre-publish check: **one piece of content, three views compared**.

## Run it in three steps

1. Open **Content QA** and choose a type (product / page / collection / article).
2. Enter the page path (e.g. `/products/xxx`) and click **Run**.
3. Read the result: PASS / WARN / FAIL, each with a reason and evidence location.

## How to read the result

- **PASS**: the three views agree; safe to publish;
- **WARN**: risk exists (e.g. raw-md missing), not blocking;
- **FAIL**: hard error (e.g. missing Product schema); fix before publishing.

> We never turn "unmeasured" into "passed": it is explicitly reported.

**Want the rules?** Read the expert version: [[content-qa.expert]]


---


# Content QA (Expert): Rules, Template Differences and Automation

## Chapter 1: Rules and template differences

### 1.1 Three views

| View | Source | Focus |
|---|---|---|
| DOM | rendered page | FAQ count/anchors, visible text |
| JSON-LD | `<script type=ld+json>` | Product/Offer required fields, FAQPage mainEntity, @id/url |
| raw-md | `?view=raw-md` output | same anchors, prices/specs, no empty values |

### 1.2 Template awareness

- product: requires `Product` + `Offer` (price/currency/availability);
- page/collection/article: page-type Schema (`FAQPage`/`CollectionPage`/`Article`/`Organization`), not product rules;
- missing raw-md → `RAWMD_FETCH_UNAVAILABLE` (unmeasured, never fake PASS).

### 1.3 Result model

`PASS / WARN / FAIL` + `reasons[]` + `evidence` (field location / snippet / hash). Repeated runs on the same input should be reproducible (except timestamps/versions).

## Chapter 2: Automation and troubleshooting

### 2.1 API

- Single run: `POST /api/v1/content-qa/run` (`type` + `path`)
- Batch: `content-qa/batches` (enumerated by type, queued)
- Results stored in `content_qa_runs` (`mode` / `target_type`)

### 2.2 Common FAILs

| Cause | Fix |
|---|---|
| `JSONLD_PRODUCT_REQUIRED` | Add Product/Offer or check theme |
| FAQ count mismatch | page FAQ = raw-md Q = JSON-LD mainEntity |
| raw-md empty values | check `custom.specs` / variant data source |
| full theme HTML as raw-md | raw-md template missing or HTML fallback |

### 2.3 Relation to delivery

Content QA is a **pre-gate** in the delivery DAG: FAIL blocks publish; WARN needs human confirmation; only PASS goes to approval/publish/readback/rollback.

**Back to beginner version:** [[content-qa.novice]]