Structured data fundamentals for Technical SEO developers

When a search engine crawls your website, it sees raw HTML—just tags and text. Without explicit markup describing what that content means, Google has to guess: Is this article about software engineering or finance? Is this person a developer or a CEO? Structured data fundamentals solve this problem by adding a machine-readable layer to your content, giving search engines the context they need to understand, index, and display your pages more effectively.

By Day 28 of this SEO journey, you've optimized titles, meta descriptions, and heading hierarchies. Structured data is the next evolution: it's your chance to tell search engines exactly what your content is about, in a format they understand natively. This matters for rich results, knowledge panels, featured snippets, and overall crawl efficiency.

JSON-LD is preferred — A script tag in the head, separate from your HTML markup

There are three ways to markup structured data: Microdata (HTML attributes), RDFa (semantic HTML), and JSON-LD (JavaScript Object Notation for Linked Data). For modern websites, JSON-LD is the clear winner. It lives in a <script type="application/ld+json"> tag, usually in the <head>, and remains completely separate from your HTML structure. This separation is critical: your markup stays clean, your data stays maintainable, and you can test or update schemas without touching your layout.

JSON-LD's key advantage is simplicity. Unlike Microdata, which requires sprinkling attributes throughout your HTML, JSON-LD is a self-contained JSON block. Search engines prefer it because it's unambiguous, easier to parse, and less prone to human error. You can even add multiple JSON-LD blocks on a single page—for instance, one for the article itself and another for the organization publishing it.

Here's what a minimal JSON-LD block looks like:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Structured data fundamentals",
  "description": "Describe your content in a language machines understand",
  "datePublished": "2024-01-28",
  "author": {
    "@type": "Organization",
    "name": "Expona"
  }
}
</script>

Every JSON-LD block must start with "@context": "https://schema.org" and declare its "@type". That type—Article, Product, LocalBusiness, etc.—tells the parser what properties to expect. The properties themselves should match your content exactly. If you're marking up an article, include the headline, publish date, and author. Don't add fields just because the schema allows them; only include what's relevant and true.

Place your JSON-LD in the <head> or <body>—Google processes both. We recommend the <head> for clarity, especially on content-heavy pages where you might have multiple blocks. Tools like Google's Structured Data Testing Tool can validate your JSON-LD syntax and catch errors before they affect crawling.

Use schema.org types — Article, Product, Organization, Person, BreadcrumbList, LocalBusiness

Schema.org is the standard vocabulary for structured data. It's maintained collaboratively by Google, Microsoft, Yahoo, and Yandex, and it defines thousands of types and properties. You don't need to memorize all of them—just know the ones relevant to your site.

For a developer-focused publication like Expona, the most common types are:

• Article: Blog posts, news, tutorials. Use this for any long-form written content. Properties include headline, datePublished, dateModified, author, description, and image.
• Product: Physical or digital products. Include name, description, price, priceCurrency, availability, and aggregateRating.
• Organization: Your company. Use name, url, logo, sameAs (for social profiles), and contactPoint.
• Person: Team members or contributors. Include name, jobTitle, url, and image.
• BreadcrumbList: Navigation hierarchy. Helps users and crawlers understand site structure. Each item has a position, name, and item URL.
• LocalBusiness: If you have a physical office. Include name, address, telephone, openingHoursSpecification, and geo.

Let's say you're documenting a security tunnel product. Your Product schema might look like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Expona Secure Tunnel",
  "description": "End-to-end encrypted tunnels for remote access and edge networking",
  "image": "https://expona.dev/images/tunnel-hero.png",
  "brand": {
    "@type": "Brand",
    "name": "Expona"
  },
  "offers": {
    "@type": "Offer",
    "price": "99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "reviewCount": "124"
  }
}
</script>

For a team member profile, Person markup adds credibility and can appear in knowledge panels:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Senior Backend Engineer",
  "jobTitle": "Senior Backend Engineer",
  "url": "https://expona.dev/team",
  "image": "https://expona.dev/images/team-member.jpg",
  "worksFor": {
    "@type": "Organization",
    "name": "Expona"
  }
}
</script>

Choosing the right type is about accuracy. If you force a Product schema onto a blog post, or an Article schema onto a landing page, you're misleading the parser. Match the schema to your content's true nature.

Match visible content — Markup must describe what users can see on the page

This is the golden rule of structured data: never markup anything that isn't visible or truthful on the page. If your headline in the schema is "Buy Now" but the visible headline is "10 Ways to Optimize Your Database," you've created a mismatch. Google's algorithms detect these inconsistencies and may penalize your site or simply ignore the markup.

Consider a common scenario: you're syndicating an article from a partner publication. Your page displays their original headline and content. The JSON-LD should reflect what visitors actually see, not some hidden metadata. If you've edited the headline for your audience, use your edited version. If you've added your own commentary, include that in the author field or description.

Here's a practical example. Your engineering blog publishes weekly tutorials. Each tutorial page has:

• A headline: "Building WebSocket servers with NestJS"
• A publish date: January 28, 2024
• An author or organization: Expona
• A featured image: a diagram showing WebSocket architecture
• A first paragraph describing the tutorial's scope

Your Article markup should use these exact values:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Building WebSocket servers with NestJS",
  "datePublished": "2024-01-28",
  "dateModified": "2024-01-28",
  "author": {
    "@type": "Organization",
    "name": "Expona"
  },
  "description": "Learn how to implement real-time communication using WebSockets in NestJS with practical examples and production patterns.",
  "image": "https://expona.dev/images/websocket-diagram.png",
  "articleBody": ""
}
</script>

Don't inflate dates. Don't use stock descriptions. Don't pull images from CDNs that users can't access. Every field should match what a human reading the page would encounter. This builds trust with search engines and ensures your markup gets used, not ignored.

Rich results are not guaranteed — Valid markup makes you eligible — Google decides what to show

Adding structured data doesn't automatically trigger rich results. It makes you eligible for them. Google still decides, based on its own algorithms and policies, whether your content deserves a rich snippet, a knowledge panel, or a special SERP treatment.

Valid JSON-LD is necessary but not sufficient. Google also evaluates:

• Content quality: Is the article well-written, authoritative, and original?
• E-E-A-T signals: Expertise, Experience, Authoritativeness, Trustworthiness. This includes backlinks, domain age, and topical authority.
• Policy compliance: Does the content violate Google's policies on hate speech, misinformation, or dangerous content?
• User signals: CTR, bounce rate, time on page—these hint at relevance and satisfaction.
• Schema accuracy: Does the markup genuinely reflect what's on the page?

A poorly written article with perfect JSON-LD won't get rich results. A high-quality article with missing or invalid JSON-LD will still rank, but it might not appear as a rich snippet.

Use Google Search Console's Rich Results Report (under "Enhancements") to see which of your pages have rich results, which are eligible but not shown, and which have markup errors. This feedback loop is invaluable. If a page shows "valid but not shown," investigate: Is the content thin? Is the domain new? Are there competitive pages with stronger E-E-A-T signals?

For SaaS or e-commerce sites, rich results can increase CTR by 20-40%. A product with a star rating, price, and availability appears more attractive in search results. An article with a thumbnail and publication date looks more credible. But these improvements only manifest if Google chooses to show them. Your job is to provide clean, honest markup and let Google make the decision.

Common mistakes

Even experienced developers sometimes create problematic structured data. Here are the pitfalls we've seen in production:

• Mismatched types: Using Article markup on a homepage or Product markup on a blog. Choose the type that matches the page's primary content.
• Hidden or invisible content: Marking up text that users can't see, or markup that doesn't align with visible content. Google catches these inconsistencies.
• Duplicate or conflicting markup: Multiple JSON-LD blocks on one page that contradict each other. If a page has both Article and Product schemas with different titles, the parser gets confused.
• Incomplete required fields: Some properties are effectively required for rich results. An Article without a publication date is less likely to show rich snippets. A Product without a price or availability is incomplete.
• Invalid JSON syntax: A missing comma, unescaped quote, or nested object error breaks the entire block. Always validate with the Structured Data Testing Tool.
• Overstuffing keywords: Adding irrelevant markup to game search rankings. Google penalizes schema spam. Use markup truthfully.
• Not updating dateModified: If you edit an article, update the dateModified field. This signals to Google that the content is fresh and maintained.

Key takeaways

• JSON-LD is the modern standard for structured data; place it in a <script> tag in your <head> or <body>, separate from HTML markup.
• Use schema.org vocabulary: Article, Product, Organization, Person, BreadcrumbList, and LocalBusiness cover most developer and SaaS use cases.
• Every field in your markup must reflect what users actually see on the page—accuracy and honesty are non-negotiable.
• Valid markup makes you eligible for rich results, but Google's algorithms ultimately decide whether to display them based on content quality, E-E-A-T, and user signals.
• Validate your JSON-LD syntax with Google's Structured Data Testing Tool and monitor rich results in Search Console's Enhancements report.
• Update dateModified when you edit content, and avoid markup spam or keyword stuffing—it damages trust and SEO performance.