Fact Check Schema Framework

function isAbsoluteUrl(value) {
  if (typeof value !== "string") return false;
  try {
    const url = new URL(value);
    return url.protocol === "https:" || url.protocol === "http:";
  } catch {
    return false;
  }
}

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?$/;

function toIsoDate(value) {
  if (typeof value !== "string" || !ISO_DATE.test(value.trim())) return null;
  return isNaN(Date.parse(value.trim())) ? null : value.trim();
}

function toIsoDateTime(value) {
  if (typeof value !== "string" || !ISO_DATETIME.test(value.trim())) return null;
  // keep the original string so the timezone offset survives
  return isNaN(Date.parse(value.trim())) ? null : value.trim();
}

function compact(value) {
  if (Array.isArray(value)) {
    const items = value.map(compact).filter((item) => item !== undefined);
    return items.length ? items : undefined;
  }
  if (value && typeof value === "object") {
    const out = {};
    for (const [key, item] of Object.entries(value)) {
      const kept = compact(item);
      if (kept !== undefined) out[key] = kept;
    }
    return Object.keys(out).length ? out : undefined;
  }
  if (value === null || value === undefined || value === "") return undefined;
  return value;
}

function buildRating(verdict) {
  // the textual verdict is required: alternateName, or name when alternateName is absent
  const label = (verdict.label || "").trim();
  if (!label) return null;
  const rating = { "@type": "Rating", "alternateName": label, "name": label };

  const { value, worst, best } = verdict;
  const numeric = [value, worst, best].every((n) => typeof n === "number" && isFinite(n));
  if (numeric) {
    // worstRating at least 1 and below bestRating; ratingValue inside the scale
    if (worst < 1 || worst >= best || value < worst || value > best) return null;
    Object.assign(rating, { "ratingValue": value, "worstRating": worst, "bestRating": best });
  }
  return rating;
}

function buildClaim(claim) {
  if (!claim) return null;
  return {
    "@type": "Claim",
    "author": claim.authorName
      ? {
          "@type": claim.authorType === "Person" ? "Person" : "Organization",
          "name": claim.authorName,
          "sameAs": isAbsoluteUrl(claim.authorSameAs) ? claim.authorSameAs : null
        }
      : null,
    "datePublished": toIsoDateTime(claim.datePublished) || toIsoDate(claim.datePublished),
    "appearance": (claim.appearances || []).filter(isAbsoluteUrl),
    "firstAppearance": isAbsoluteUrl(claim.firstAppearance) ? claim.firstAppearance : null
  };
}

function buildClaimReviewSchema(source) {
  // Google is phasing out ClaimReview rich results; emit only for a visible fact check
  // (schema.org semantics, Fact Check Explorer and other consumers)
  if (source.indexable === false) return null;
  if (!isAbsoluteUrl(source.url)) return null;
  if (source.canonicalUrl && source.canonicalUrl !== source.url) return null;
  if (source.verdictVisible !== true) return null; // claim and conclusion must be readable on the page
  if ((source.claimReviewsOnPage ?? 1) !== 1) return null; // one ClaimReview per page

  const claimReviewed = (source.claimSummary || "").trim();
  if (!claimReviewed) return null;
  const reviewRating = buildRating(source.verdict || {});
  if (!reviewRating) return null;

  const schema = {
    "@context": "https://schema.org",
    "@type": "ClaimReview",
    "url": source.url, // the page hosting the full fact check article
    "claimReviewed": claimReviewed, // keep under 75 characters to limit wrapping on mobile
    "reviewRating": reviewRating,
    "author": source.publisher
      ? {
          "@type": "Organization",
          "name": source.publisher.name,
          "url": isAbsoluteUrl(source.publisher.url) ? source.publisher.url : null
        }
      : null,
    "itemReviewed": buildClaim(source.claim)
  };

  return compact(schema);
}

// Usage:
// buildClaimReviewSchema({
//   url: "https://www.example.com/fact-checks/2026/moon-cheese",
//   canonicalUrl: "https://www.example.com/fact-checks/2026/moon-cheese",
//   indexable: true,
//   verdictVisible: true,
//   claimReviewsOnPage: 1,
//   claimSummary: "The moon is made of cheese",
//   verdict: { label: "False", value: 1, worst: 1, best: 5 },
//   publisher: { name: "Example Fact Desk", url: "https://www.example.com/about/corrections-policy" },
//   claim: {
//     authorName: "Square Moon Society",
//     authorSameAs: "https://www.example.org/square-moon-society",
//     datePublished: "2026-04-02",
//     appearances: ["https://www.example.org/posts/moon-facts"],
//     firstAppearance: "https://www.example.org/posts/moon-facts"
//   }
// });

import math
import re
from datetime import date, datetime
from urllib.parse import urlparse


def is_absolute_url(value):
    if not isinstance(value, str):
        return False
    parsed = urlparse(value)
    return parsed.scheme in ("http", "https") and bool(parsed.netloc)


ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
ISO_DATETIME = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?$")


def to_iso_date(value):
    if not isinstance(value, str) or not ISO_DATE.match(value.strip()):
        return None
    try:
        date.fromisoformat(value.strip())
    except ValueError:
        return None
    return value.strip()


def to_iso_datetime(value):
    if not isinstance(value, str) or not ISO_DATETIME.match(value.strip()):
        return None
    # keep the original string so the timezone offset survives
    try:
        datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
    except ValueError:
        return None
    return value.strip()


def compact(value):
    if isinstance(value, list):
        items = [kept for kept in (compact(item) for item in value) if kept is not None]
        return items or None
    if isinstance(value, dict):
        out = {}
        for key, item in value.items():
            kept = compact(item)
            if kept is not None:
                out[key] = kept
        return out or None
    if value is None or value == "":
        return None
    return value


def is_number(value):
    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)


def build_rating(verdict):
    # the textual verdict is required: alternateName, or name when alternateName is absent
    label = (verdict.get("label") or "").strip()
    if not label:
        return None
    rating = {"@type": "Rating", "alternateName": label, "name": label}

    value, worst, best = verdict.get("value"), verdict.get("worst"), verdict.get("best")
    if all(is_number(n) for n in (value, worst, best)):
        # worstRating at least 1 and below bestRating; ratingValue inside the scale
        if worst < 1 or worst >= best or value < worst or value > best:
            return None
        rating.update({"ratingValue": value, "worstRating": worst, "bestRating": best})
    return rating


def build_claim(claim):
    if not claim:
        return None
    return {
        "@type": "Claim",
        "author": {
            "@type": "Person" if claim.get("authorType") == "Person" else "Organization",
            "name": claim["authorName"],
            "sameAs": claim.get("authorSameAs") if is_absolute_url(claim.get("authorSameAs")) else None,
        } if claim.get("authorName") else None,
        "datePublished": to_iso_datetime(claim.get("datePublished")) or to_iso_date(claim.get("datePublished")),
        "appearance": [u for u in claim.get("appearances") or [] if is_absolute_url(u)],
        "firstAppearance": claim.get("firstAppearance") if is_absolute_url(claim.get("firstAppearance")) else None,
    }


def build_claim_review_schema(source):
    # Google is phasing out ClaimReview rich results; emit only for a visible fact check
    # (schema.org semantics, Fact Check Explorer and other consumers)
    if source.get("indexable") is False:
        return None
    if not is_absolute_url(source.get("url")):
        return None
    if source.get("canonicalUrl") and source["canonicalUrl"] != source["url"]:
        return None
    if source.get("verdictVisible") is not True:
        return None  # claim and conclusion must be readable on the page
    reviews_on_page = source.get("claimReviewsOnPage")
    if (1 if reviews_on_page is None else reviews_on_page) != 1:
        return None  # one ClaimReview per page

    claim_reviewed = (source.get("claimSummary") or "").strip()
    if not claim_reviewed:
        return None
    review_rating = build_rating(source.get("verdict") or {})
    if not review_rating:
        return None

    publisher = source.get("publisher")
    schema = {
        "@context": "https://schema.org",
        "@type": "ClaimReview",
        "url": source["url"],  # the page hosting the full fact check article
        "claimReviewed": claim_reviewed,  # keep under 75 characters to limit wrapping on mobile
        "reviewRating": review_rating,
        "author": {
            "@type": "Organization",
            "name": publisher.get("name"),
            "url": publisher.get("url") if is_absolute_url(publisher.get("url")) else None,
        } if publisher else None,
        "itemReviewed": build_claim(source.get("claim")),
    }

    return compact(schema)


# Usage:
# build_claim_review_schema({
#     "url": "https://www.example.com/fact-checks/2026/moon-cheese",
#     "canonicalUrl": "https://www.example.com/fact-checks/2026/moon-cheese",
#     "indexable": True,
#     "verdictVisible": True,
#     "claimReviewsOnPage": 1,
#     "claimSummary": "The moon is made of cheese",
#     "verdict": {"label": "False", "value": 1, "worst": 1, "best": 5},
#     "publisher": {"name": "Example Fact Desk", "url": "https://www.example.com/about/corrections-policy"},
#     "claim": {
#         "authorName": "Square Moon Society",
#         "authorSameAs": "https://www.example.org/square-moon-society",
#         "datePublished": "2026-04-02",
#         "appearances": ["https://www.example.org/posts/moon-facts"],
#         "firstAppearance": "https://www.example.org/posts/moon-facts",
#     },
# })

{
  "@context": "https://schema.org",
  "@type": "ClaimReview",
  "url": "https://www.example.com/fact-checks/2026/moon-cheese",
  "claimReviewed": "The moon is made of cheese",
  "reviewRating": {
    "@type": "Rating",
    "alternateName": "False",
    "name": "False",
    "ratingValue": 1,
    "worstRating": 1,
    "bestRating": 5
  },
  "author": {
    "@type": "Organization",
    "name": "Example Fact Desk",
    "url": "https://www.example.com/about/corrections-policy"
  },
  "itemReviewed": {
    "@type": "Claim",
    "author": {
      "@type": "Organization",
      "name": "Square Moon Society",
      "sameAs": "https://www.example.org/square-moon-society"
    },
    "datePublished": "2026-04-02",
    "appearance": [
      "https://www.example.org/posts/moon-facts"
    ],
    "firstAppearance": "https://www.example.org/posts/moon-facts"
  }
}