@mdwrk/structured-data

Schema.org and JSON-LD helpers

This package provides reusable Schema.org and JSON-LD builders for MdWrk apps, packages, public content, and discovery surfaces.

Why

Use it when you need structured-data output without rewriting low-level Schema.org node creation logic.

What

• Builders for WebPage, WebSite, FAQPage, SoftwareApplication, TechArticle, Product, Dataset, and more.
• Helpers for canonical ids and graph assembly.
• A shared discovery layer consumed heavily by the lander stack.

Installation

Node.js 20.x through 22.x, matching the workspace engine contract in the root package manifest.

npm install @mdwrk/structured-data

Usage

import { faqPageSchema, jsonLdGraph, softwareApplicationNode } from "@mdwrk/structured-data";

const graph = jsonLdGraph([
  softwareApplicationNode({ name: "MdWrk", url: "https://mdwrk.com" }),
  faqPageSchema({ items: [{ question: "What is MdWrk?", answer: "A markdown workspace platform." }] }),
]);

Schema Conformance Policy

• Emitted JSON-LD is generator-backed and must remain valid against the Schema.org-derived contract surface in @mdwrk/lander-content-contract.
• Repo-local authored helper fields must not leak into emitted JSON-LD unless they are mapped to a real Schema.org field.
• Current fail-closed helper examples:
  • SearchResultsPageInput.query is authoring-only and is never emitted.
  • SolveMathActionInput.mathExpressionInput is authoring-only and is never emitted.
  • LoyaltyProgramInput.provider is authoring-only in the current governed surface and is never emitted.
  • estimatedSalaryNode(...).unitText is authoring-only; it is mapped only when it is already a schema-valid ISO duration, otherwise it is dropped.
• Run npm run test:schema-conformance -w @mdwrk/structured-data to prove the builder layer still honors this contract.

Related

• Packages index - family and package navigation
• Root README - repo overview