Skip to Content

Validation

Validate graphs, metadata, Schema.org definitions, and rich-result profiles.

@puzzle-ui/seo reports graph, schema, semantic, metadata, registry, rich-result, and custom validation diagnostics.

Install

npm install @puzzle-ui/seo react

React 19 is a peer dependency. Framework adapters do not require a framework package at runtime.

Quick start

import { buildSeoGraph } from "@puzzle-ui/seo/core";
import { validateSeo } from "@puzzle-ui/seo/validation";

const graph = buildSeoGraph([
  { "@type": "Organization", name: "Example", url: "https://example.com" },
], { baseUrl: "https://example.com" });

const report = validateSeo({ graph, metadata: { title: "Welcome to Example", description: "Discover the Example website and its services.", canonical: "https://example.com/" } }, {
  mode: "strict",
  baseUrl: "https://example.com",
});
if (!report.valid) console.error(report.issues);

A report contains valid, mode, issues, and summary counts. Each issue includes a severity, source, code and message, and may include a path, suggestion or documentation URL. Warnings are promoted to errors in strict mode. Validation is guidance, not a guarantee of search engine eligibility or indexing.

Options

NameTypeDefaultDescription
mode"off" | "warn" | "strict""warn"Disable checks, report issues, or promote warnings to errors.
registrySchemaRegistrygenerated default registryDefinitions used for schema validation.
profilesSeoRichResultProfile[]—Additional rich-result checks.
validatorsSeoCustomValidator[]—Custom validators returning issues.
validateRequiredPropertiesbooleanfalseCheck required schema properties.
allowExternalReferencesbooleantruePermit external graph references.
baseUrlstring—Resolve local references against this URL.
allowUnknownPropertiesbooleantrue in warn, false in strictPermit unrecognized Schema.org properties.

Profiles are article, product, breadcrumb, event, recipe, job-posting, local-business, and software-application. Choose profiles appropriate for the actual content rather than marking up content that is absent from the page.

React validation

import { LDOrganization, SeoProvider } from "@puzzle-ui/seo/react";

const App = () => (
  <SeoProvider
    config={{ siteUrl: "https://example.com" }}
    metadata={{ title: "Welcome to Example", description: "Discover the Example website and its services.", canonical: "/" }}
    validation={{ mode: "strict" }}
    onValidation={(report) => console.log(report.summary)}
  >
    <LDOrganization name="Example" />
  </SeoProvider>
);

Warn mode keeps rendering even when the validation report is invalid; strict mode throws before output when its report is invalid. The callback runs in a React effect, not during server rendering, so validate explicitly on the server if you need diagnostics there. validation={false} disables the complete validation report, not independent graph-builder errors. Legacy validation={{ strict: true }} remains supported; prefer mode for new code.

Exports

@puzzle-ui/seo/validation exports validateSeo, validateSeoMetadata, validateSeoNode, and validation option, input, report, issue and profile types. The root also exports these functions; its SeoValidationIssue type is the core graph issue, while SeoValidationReportIssue aliases the richer validation issue type.