DEV Community: Randy Rodriguez

The JSON-LD Playbook for Local Business Sites (and the mistake that quietly tanks it)

Randy Rodriguez — Thu, 23 Jul 2026 16:15:31 +0000

Structured data is how a search engine (and now an AI answer engine) understands what your site "is", not just what words it contains. Done right, it unlocks rich results, knowledge panels, and citations in ChatGPT and Perplexity. Done wrong, it silently sends conflicting signals that cancel each other out.

I recently shipped a local service site and spent real time getting the schema correct. Here's the playbook, plus the one mistake I see on almost every local site.

Where JSON-LD lives

JSON-LD is just a <script type="application/ld+json"> block. Framework-agnostic. In React/Next you can render it with a tiny component:

function JsonLd({ data }) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
}

That's the whole mechanism. Everything else is getting the object right.

The core: one business node in an @graph

Use a specific LocalBusiness subtype when one exists (HVACBusiness, Dentist, Plumber, Restaurant), and give it a stable @id so other nodes can reference it. Wrapping everything in an @graph lets you ship multiple linked nodes in a single script:

const graph = {
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      url: "https://example.com",
      publisher: { "@id": "https://example.com/#business" },
    },
    {
      "@type": "HVACBusiness",
      "@id": "https://example.com/#business",
      name: "Broward AC Guys",
      telephone: "+17868371512",
      priceRange: "$$",
      areaServed: [
        { "@type": "AdministrativeArea", name: "Broward County, FL" },
        { "@type": "AdministrativeArea", name: "Miami-Dade County, FL" },
      ],
      openingHoursSpecification: {
        "@type": "OpeningHoursSpecification",
        dayOfWeek: ["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],
        opens: "00:00",
        closes: "23:59",
      },
    },
  ],
};

The @id is the important part. It turns loose objects into a connected graph a crawler can reason about.

The mistake: a LocalBusiness on every location page

Here's the one that quietly hurts you. Local sites often have a page per city (/service-areas/miami, /service-areas/hollywood, ...) and drop a full LocalBusiness block on each, changing only the city name.

You just told Google you have a dozen businesses that share one name and one phone number. That's a NAP (name/address/phone) consistency problem, and it dilutes the single entity you actually want to rank.

Fix: location pages describe a "service", not a separate business. Emit a Service node that points back to your one business via @id:

const serviceSchema = {
  "@context": "https://schema.org",
  "@type": "Service",
  serviceType: "Air conditioning repair",
  name: `AC Repair in ${city}, FL`,
  provider: { "@id": "https://example.com/#business" },
  areaServed: { "@type": "City", name: `${city}, FL` },
};

One business, many services, many areas. Consistent every time.

Service-area businesses: hide the address on purpose

If you run a service-area business (you go to the customer, and your Google Business Profile hides the street address), do not invent a street address for schema. A fake or mismatched address is worse than none.

Publish locality and region only, and let areaServed carry the coverage:

address: {
  "@type": "PostalAddress",
  addressLocality: "Fort Lauderdale",
  addressRegion: "FL",
  addressCountry: "US",
},

Match this to whatever your Google Business Profile actually shows. Consistency between your schema, your site, and your GBP is the whole game.

Free wins: FAQPage and BreadcrumbList

If you already have FAQ content, wrap it in FAQPage schema. Both Google and LLM assistants consume it, and it's a direct map of your data:

const faqSchema = {
  "@context": "https://schema.org",
  "@type": "FAQPage",
  mainEntity: faqs.map((f) => ({
    "@type": "Question",
    name: f.q,
    acceptedAnswer: { "@type": "Answer", text: f.a },
  })),
};

Add BreadcrumbList on inner pages so the crawler understands your hierarchy and can show breadcrumb rich results:

const breadcrumb = {
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  itemListElement: [
    { "@type": "ListItem", position: 1, name: "Home", item: "https://example.com" },
    { "@type": "ListItem", position: 2, name: "Service Areas", item: "https://example.com/locations" },
  ],
};

Validate before you ship

Never eyeball JSON-LD. Run it through:

Google's Rich Results Test
The Schema Markup Validator

A quick programmatic check also catches broken JSON before deploy:

document.querySelectorAll('script[type="application/ld+json"]')
  .forEach((s) => JSON.parse(s.textContent)); // throws on invalid JSON

You can inspect a full, validating example live on browardacguys.com (view source and search for application/ld+json).

The takeaway

Structured data is not about volume, it's about a single, consistent, connected entity:

One business node with a stable @id.
Location pages use Service + areaServed, never a second LocalBusiness.
Match your address handling to your real Google Business Profile.
Add FAQPage and BreadcrumbList from data you already have.
Validate every time.

Get those five right and you've done more for your local search presence than another 1,000 words of body copy. The complete implementation is running on the live site if you want a reference.

Building a Fast, SEO-First Local Business Site with Next.js App Router

Randy Rodriguez — Thu, 23 Jul 2026 16:08:15 +0000

Most local business websites are slow, template-bloated, and invisible to search. I recently built one that scores 100 on Lighthouse SEO and Best Practices, ships zero client-side CMS weight, and generates its own sitemap, structured data, and AI-crawler manifest from a single data file. Here's how, with code you can lift into your own project.

The finished result is live at browardacguys.com if you want to view-source along the way.

One data file, many pages

The trick to a maintainable local site is to treat pages as dataities live in plain arrays, and dynamic routes generate a pageper entry.

// lib/services.js
export const services = [
  {
    slug: "emergency-ac-repair",
    name: "Emergency AC Repair",
    title: "24/7 Emergency AC Repair",
    metaDescription: "AC out at 2 a.m.? Same-day emergency repai
    summary: "When your AC quits, waiting is not an option.",
    faqs: [{ q: "Do you answer at night?", a: "Yes, 24/7 dispatc
  },
  // ...
];

export const getService = (slug) => services.find((s) => s.slug === slug);

// app/services/[slug]/page.js
import { services, getService } from "@/lib/services";

export function generateStaticParams() {
  return services.map((s) => ({ slug: s.slug }));
}

Add a service to the array and you get a new statically-rendered page, a sitemap entry, and internal links, all for free.

Per-page metadata with the Metadata API

Next's Metadata API makes unique title tags and descriptions trivial. generateMetadata runs per route:

export async function generateMetadata({ params }) {
  const { slug } = await params;
  const service = getService(slug);
  return {
    title: { absolute: service.title },
    description: service.metaDescription,
    alternates: { canonical: `/services/${service.slug}` },
    openGraph: { title: service.title, images: ["/og.jpg"] },
  };
}

Note title: { absolute } to bypass a site-wide title template complete, so you don't blow past the ~60 character SERP limit.

Structured data that actually validates

Rich results need JSON-LD. I use a single @graph with the busi, FAQPage, and BreadcrumbList nodes. The key detail for aservice-area business: do NOT emit a LocalBusiness per city (that creates duplicate NAP entities). Use one business node and reference it.

const graph = {
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "HVACBusiness",
      "@id": "https://example.com/#business",
      name: "Broward AC Guys",
      telephone: "+17868371512",
      areaServed: [{ "@type": "AdministrativeArea", name: "Browa
      openingHoursSpecification: {
        "@type": "OpeningHoursSpecification",
        opens: "00:00", closes: "23:59",
      },
    },
  ],
};

A FAQPage node on pages with FAQs is a cheap win, since Googleme it.

Sitemap and robots as code

No plugins. Next turns these functions into /sitemap.xml and `

js // app/sitemap.js export default function sitemap() { const lastModified = new Date(); return services.map((s) => ({ url:https://example.com/services/${s.slug}`,
lastModified,
changeFrequency: "monthly",
}));
}
`

An llms.txt for AI crawlers

As people ask ChatGPT and Perplexity for local recommendations, p of your site is worth the five minutes. The llms.txtspec is just markdown. I generate it from the same data so it never drifts:

js // app/llms.txt/route.js export function GET() { const body =# Broward AC Guys\n\n> 24/7 AC repair...\n\n## S
services.map((s) => - [${s.name}](/services/${s.slug})).join("\n");
return new Response(body, { headers: { "Content-Type": "text/p
}
`

You can see the [live llms.txt here](https://browardacguys.com/l

6. Images without the LCP penalty

next/image plus AVIF cut the hero image roughly in half:

js // next.config.mjs export default { images: { formats: ["image/avif", "image/webp"]

Set priority on the LCP image so it preloads, and give every image a fixed aspect-ratio container so your CLS stays at 0.

7. Analytics events without hurting Core Web Vitals

I load GA4 via @next/third-parties (after-interactive, no CWV hit), then track phone-call clicks with one delegated listener instead of wiring every button:

`js
"use client";
import { useEffect } from "react";

export default function AnalyticsEvents() {
useEffect(() => {
const onClick = (e) => {
const a = e.target.closest?.("a");
if (a?.getAttribute("href")?.startsWith("tel:")) {
window.gtag?.("event", "phone_call", { page_path: locati
}
};
document.addEventListener("click", onClick);
return () => document.removeEventListener("click", onClick);
}, []);
return null;
}
`

The results

On mobile PageSpeed (throttled Slow 4G, emulated budget phone):

Performance 85, Accessibility 96, Best Practices 100, SEO 100
CLS 0, Total Blocking Time 20ms
Structured data validates with zero errors

Static-first rendering plus a data-driven architecture gets you full build (schema, sitemap, llms.txt, event tracking) is running on the live site (https://browardacguys.com).

If you're building something similar, the biggest lever is the boring one: keep your content in data, render it statically, and let the framework generate the SEO plumbing for you.