Learn About Schemas — Guides & Tutorials
Free, in-depth guides on structured data markup, database design, and API development.
How to use this library
Each guide here is built around a single decision or workflow rather than a topical overview. If you read one all the way through you should leave with a usable answer — not a checklist of things to look up later. The guides assume you can read code but not that you have prior expertise in the topic; every term is defined the first time it appears.
Three reading paths cover most cases. If you have never added structured data before, start with the Beginner's Guide to Schema Markup, then read JSON-LD vs Microdata vs RDFa to understand the format choice, then read Structured Data for AI Search Engines once you are ready to optimize. If your work is server-side, read Database Schema Design Fundamentals for the relational basics and the JSON Schema Guide for API contracts. If you maintain a public API, the API Versioning Best Practices guide is the highest-leverage thing you can read this quarter.
Every guide links back to the relevant tool on the site so you can apply what you learn against a real example as you read. The tools are free and require no signup.
How the library is organized
The guides are grouped under three categories that match the structure of the rest of the site. Markup covers Schema.org structured data: what it is, why it matters for both classic search and AI-driven search, which format to choose, and how to write JSON-LD that is both valid and citation-ready. Database covers the relational schema fundamentals every application engineer ends up needing — normalization, relationships, naming, audit columns, soft deletes — written without the academic jargon that surrounds the topic in textbooks. API covers JSON Schema and OpenAPI: how to describe payloads and contracts, how to evolve them without breaking consumers, and how to detect breaking changes before they ship. Every guide is written to be read in one sitting and to leave you with one fewer decision to make.
Pages here are intentionally not stub articles padded out with synonyms. We aim for working-engineer length: long enough to cover the material, short enough that you finish. Where a topic has a long tail of edge cases, we link out to the canonical specification — the W3C document, the IETF RFC, the Schema.org type page, the Postgres or MySQL reference manual — rather than inflate the guide. Each guide closes with a Sources and further reading section listing every external reference, so you can verify any claim or dig deeper without having to search for it.
Drawn from production work, the guides reflect decisions our team has made on real projects. Where there is a single clear answer we say so. Where the answer is "it depends," we name the variables and the trade-offs instead of hedging with weasel words. The structure of each guide is consistent: a short framing of the problem, the conceptual material, a worked example, and a closing decision rule you can apply tomorrow.
The Complete Beginner's Guide to Schema Markup
A complete walk-through for adding structured data to a website for the first time. Covers what schema markup is, why search engines and AI assistants use it, the difference between Schema.org types and Google's rich result requirements, and how to write, validate, and ship your first JSON-LD block. Worked examples for Article, Product, FAQ, and LocalBusiness, with notes on how each one renders in search.
JSON-LD vs Microdata vs RDFa — Which Should You Use?
A side-by-side comparison of the three Schema.org-compatible formats. Each section shows the same Article marked up in all three, lists the syntactic and maintenance trade-offs, and explains why Google has recommended JSON-LD since 2015. Also covers the edge cases where Microdata still makes sense — primarily inline rendering on legacy CMSes — and the few RDFa-specific scenarios you may encounter. Ends with a one-paragraph decision rule.
How to Optimize Structured Data for AI Search Engines
The fields and properties that influence whether AI search engines cite your pages. Covers Author identity, Publisher trust, dateModified honesty, citation completeness, and the Article subtype hierarchy that ChatGPT Search and Perplexity weigh most heavily. Includes a checklist for retrofitting an existing site, examples of optimized markup pulled from pages that consistently appear in AI overviews, and the common mistakes that make a page invisible to retrieval pipelines.
Database Schema Design Fundamentals
Normalization explained without the academic jargon, the three relationship types (one-to-one, one-to-many, many-to-many) with worked examples, naming conventions that survive a team turnover, and the patterns that come up in every project — soft deletes, audit columns, slowly-changing dimensions, lookup tables. Each section ends with a do-this-not-that rule. Written for application developers who own the schema but did not specialize in databases.
JSON Schema — The Complete Guide
Everything a working engineer needs from JSON Schema, drawn from the 2020-12 draft. Validation keywords (required, minLength, pattern, enum), format vocabularies (email, uri, uuid, date-time), composition with $ref and allOf, and the conditional logic in if/then/else. Worked examples for request validation, configuration files, and event schemas. Closes with the differences between drafts so you can read a schema written years ago without surprises.
API Schema Versioning Best Practices
A pragmatic versioning policy that survives contact with real users. Semantic versioning applied to API contracts, the difference between safe additions and warnings and breaks, deprecation windows that respect slow-moving consumers, and the URL-vs-header debate decided by use case rather than ideology. Includes a release checklist, a sample changelog format, and the contract-testing setup that catches drift before it ships.