# CLAUDE.md

## Overview

Structured data validator: extract, parse, and validate JSON-LD, Microdata, and RDFa markup against schema.org vocabulary.

## Quick Start

```bash
pip install -r scripts/requirements.txt
python scripts/schema_validator.py --url https://example.com
```

## Scripts

| Script | Purpose |
|--------|---------|
| `schema_validator.py` | Extract and validate structured data |
| `base_client.py` | Shared utilities |

## Usage

```bash
# Validate page schema
python scripts/schema_validator.py --url https://example.com

# JSON output
python scripts/schema_validator.py --url https://example.com --json

# Validate local file
python scripts/schema_validator.py --file schema.json

# Check Rich Results eligibility
python scripts/schema_validator.py --url https://example.com --rich-results
```

## Supported Formats

| Format | Detection |
|--------|-----------|
| JSON-LD | `<script type="application/ld+json">` |
| Microdata | `itemscope`, `itemtype`, `itemprop` |
| RDFa | `vocab`, `typeof`, `property` |

## Validation Levels

### 1. Syntax Validation
- Valid JSON structure
- Proper nesting
- No syntax errors

### 2. Schema.org Vocabulary
- Valid @type values
- Known properties
- Correct property types

### 3. Google Rich Results
- Required properties present
- Recommended properties
- Feature-specific requirements

## Schema Types Validated

| Type | Required Properties | Rich Result |
|------|---------------------|-------------|
| Article | headline, author, datePublished | Yes |
| Product | name, offers | Yes |
| LocalBusiness | name, address | Yes |
| FAQPage | mainEntity | Yes |
| Organization | name, url | Yes |
| BreadcrumbList | itemListElement | Yes |
| WebSite | name, url | Sitelinks |

## Output

```json
{
  "url": "https://example.com",
  "schemas_found": 3,
  "schemas": [
    {
      "@type": "Organization",
      "valid": true,
      "rich_results_eligible": true,
      "issues": [],
      "warnings": []
    }
  ],
  "summary": {
    "valid": 3,
    "invalid": 0,
    "rich_results_eligible": 2
  }
}
```

## Issue Severity

| Level | Description |
|-------|-------------|
| Error | Invalid schema, blocks rich results |
| Warning | Missing recommended property |
| Info | Optimization suggestion |

## Dependencies

```
extruct>=0.16.0
jsonschema>=4.21.0
rdflib>=7.0.0
lxml>=5.1.0
requests>=2.31.0
```

## Notion Output (Required)

**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

### Database Configuration

| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |

### Required Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Audited website URL |
| Category | Select | Technical SEO, On-page SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt, Content, Local SEO |
| Priority | Select | Critical, High, Medium, Low |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: [TYPE]-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., SEO Audit, Core Web Vitals, Schema Markup)
- URLs and code remain unchanged

### Example MCP Call

```bash
mcp-cli call notion/API-post-page '{"parent": {"database_id": "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"}, "properties": {...}}'
```