linking-and-schema

name

linking-and-schema

description

Generate an internal-linking plan and JSON-LD structured data from a brand's topical map and entity profile. Use whenever the user asks about internal links, anchor text, site structure, linking strategy, schema markup, structured data, or JSON-LD — or right after new content is drafted or published. Produces an actionable link checklist (with varied anchors) and validated per-node schema files. Triggers on linking/schema intent broadly.

linking-and-schema

Turn the map into a link graph and structured data. Both outputs are deterministic and carry the framework's fact discipline: laterals are justified (not sprayed), anchors are varied (not exact-match spam), and schema never states an ungrounded fact.

Read first: ../../framework/internal-linking-rules.md, ../../framework/schema-jsonld.md, ../../framework/eeat-signals.md.

Preconditions

• topical-map.json and entity-profile.json for the brand.
• Optional: map embeddings (for lateral justification) and crawl data (for real orphans).

Workflow

1. Internal-linking plan:

   python ../../scripts/linking_plan.py --map brands/<slug>/topical-map.json \
     [--vecs brands/<slug>/data/embeddings/map.npz --lateral-threshold 0.72] \
     [--crawl-dir brands/<slug>/data/crawl] --brand "<Brand>" \
     --out brands/<slug>/audits/linking-plan.md
   

   For each node it emits up/down/justified-lateral links with varied, descriptive anchors drawn from the target's query network, plus link-health flags (planned-graph orphans, over-linked hubs, and real crawl orphans if crawl data is present). Laterals below the embedding threshold are marked REVIEW rather than dropped or trusted.

2. JSON-LD schema:

   python ../../scripts/schema_jsonld.py --map brands/<slug>/topical-map.json \
     --entity-profile brands/<slug>/entity-profile.json \
     --locked brands/<slug>/locked-facts.json \
     --out-dir brands/<slug>/data/schema
   

   Emits one .jsonld per node (HowTo / FAQPage / Product / Article), a site-level Organization graph, and a checklist.md. Product Offer prices come ONLY from locked facts; FAQ/HowTo answer text is left as a placeholder to be filled from the validated draft — so no invented answer ships in markup.

3. Hand off: give the user the link checklist (page → insert link → suggested anchor → where) and the schema files. Note that syntactic validation here is necessary but not sufficient — run Google's Rich Results Test before publishing.

Definition of done

• Link plan covers every node; laterals justified; orphans/over-links flagged.
• One schema file per node + org graph; 0 validation issues; no fabricated price/rating.
• Anchors are varied across placements (no exact-match repetition).

Grounding ladder

• T0: link plan from map structure; laterals justified by named shared attribute (asserted). Schema from map + profile.
• T1: laterals justified by embedding distance (derived); real orphans from crawl.
• Author Person schema is emitted only when a real author/credential exists (eeat-signals.md) — never fabricated to fill the template.