Schema markup is a standardized block of structured data, usually written in JSON-LD, that you place inside a script tag on a page so search engines can read the facts you want them to understand. The markup does not change how the page looks to a visitor; it adds a machine-readable layer that crawlers parse to identify entities such as a WebSite, an Article, an Organization, a product, an event, or a person, along with the properties that connect those entities together. Once parsed, those facts can power richer search result features, including sitelinks search boxes, article carousels, knowledge panels, and review snippets, depending on what the page actually contains. In short, schema markup works by giving crawlers an explicit, vocabulary-defined description of content that would otherwise only exist as unannotated HTML.
The vocabulary behind this structured data is maintained by Schema.org, a collaborative project backed by the major search engines. When you write JSON-LD on a page, you are essentially declaring that a particular piece of content is, for example, an "Article" of type "NewsArticle" or "BlogPosting," and then listing the properties that Schema.org defines for that type — headline, author, datePublished, image, and so on. Google, Bing, and other participating crawlers recognize those terms and use them to build a clearer model of your page. The full specification lives at schema.org, which is the authoritative reference for which types and properties exist and how they relate to each other.
The Three Building Blocks of Schema Markup
Before generating any code, it helps to understand the three elements that every schema markup block shares.
- The @context: A single line that points to the schema.org vocabulary, almost always set to "https://schema.org". Without it, the block is not a recognized schema graph.
- The @type: The specific entity the block describes, such as "WebSite", "Article", "Organization", "Person", or "Product". Choosing the right type determines which properties are valid.
- The properties: Key/value pairs drawn from the Schema.org definition for that type. Values can be plain strings, URLs, dates, nested objects, or arrays of objects.
These three blocks are wrapped inside a <script> tag with a JSON-LD MIME type. Because the script is not executable JavaScript and contains no DOM hooks, browsers ignore it visually, while crawlers read it directly. That separation is what makes JSON-LD the recommended format in MDN's script element reference and in Google's own structured data documentation.
How Search Engines Read and Use the Markup
When a crawler fetches a page, it parses the HTML and looks for JSON-LD blocks. It then validates each block against the Schema.org vocabulary and against the search engine's own quality rules. Properties that match the declared type and that are consistent with the visible page content are accepted. Properties that contradict what a human reader sees on the page, or that fail validation, are ignored or flagged.
Accepted markup feeds the search engine's entity index. That index is what powers enhanced result layouts. For example, an Article block with a valid headline, image, datePublished, and author can be eligible for the article rich result. An Organization block with a logo, name, and sameAs links to social profiles can feed a knowledge panel. A WebSite block with a SearchAction can produce a sitelinks search box. None of this is guaranteed simply by adding markup; the page must genuinely contain the facts you describe.
The practical rule is simple: schema markup is a label, not an invention. If you say a page is an Article by Jane Doe published on March 4, then Jane Doe must appear as the author on the page, the date must be visible, and the headline must match what users see. The markup cannot introduce facts that the page does not already present.
WebSite, Article, and Organization: Choosing the Right Type
Most sites only need three schema types on a regular basis. The table below compares what each type describes and where it belongs on a site.
| Type | What it describes | Typical location | Key properties |
|---|---|---|---|
| WebSite | The site as a whole, including a search action | Homepage | name, url, potentialAction (SearchAction) |
| Article | An individual news, blog, or feature article | Article URL | headline, image, datePublished, author |
| Organization | The company, publisher, or brand behind the site | About page or homepage | name, logo, url, sameAs (social profiles) |
If a page is a news article, use the Article type with the appropriate subtype such as NewsArticle or BlogPosting. If a page represents the company, use Organization. If a page represents the site as a whole, use WebSite. Mixing these up, for example putting Article markup on a product page, is a common source of validation errors.
Generate JSON-LD Markup From Visible Page Facts
The fastest way to produce a clean, escaped JSON-LD block for WebSite, Article, or Organization is the Schema Markup Generator. The tool prompts you only for facts that should already be visible on the destination page, escapes the output correctly, and hands you a script you can paste straight into your HTML. Because every field is sourced from the page itself, the result is easier to validate and harder to misrepresent.
Step-by-step: building a JSON-LD block
- Open the Schema Markup Generator and choose WebSite, Article, or Organization from the type selector so the relevant fields appear.
- Gather the visible facts for the target page: the canonical URL, the headline or site name, the author or publisher name, the publish date, and any image URL that already appears on the page.
- Enter only those facts into the form. Use absolute URLs (including the protocol) for every URL field, since relative paths are not valid in JSON-LD.
- Copy the generated JSON-LD script and paste it into a <script type="application/ld+json"> block near the end of the page's <head> or just before </body>.
- Publish the page, then run the live URL through Google's Rich Results Test and the Schema Markup Validator to confirm there are no warnings or errors.
- If validation flags a missing required property, return to the generator, fill that field with a fact that genuinely appears on the page, regenerate, and re-test.
Placement, Escaping, and Common Mistakes
Where the JSON-LD block lives in the HTML does not change how a crawler parses it, but placing it in the <head> keeps the markup easy to find and audit. The script tag must declare its type as "application/ld+json", and every double quote inside string values must be escaped, which is exactly what the generator handles for you. If you ever hand-edit the output, watch for unescaped quotes, trailing commas, and stray HTML comments inside the JSON, since all three will break parsing.
Other mistakes show up frequently in real audits:
- Invented properties: Using keys that are not part of the chosen @type's definition. Crawlers ignore unknown properties, so the markup becomes incomplete.
- Mismatched facts: Declaring an author, date, or headline in the markup that does not match what the user sees on the page.
- Relative URLs: Supplying "/logo.png" instead of "https://example.com/logo.png". JSON-LD requires absolute URLs.
- Wrong type for the content: Marking a product page as an Article, or marking a blog post as a Product.
- Multiple conflicting blocks: Emitting two Organization blocks on the same page with different names or logos.
Validating and Maintaining Your Markup
Once the markup is live, validation is not a one-time event. Templates change, content teams change, and CMS plugins sometimes strip or rewrite <script> tags. A practical maintenance habit is to run a handful of important URLs through a structured data validator on a recurring schedule, not only when something visibly breaks. If a new property becomes required for a rich result you want to target, regenerate the block with the Schema Markup Generator, republish, and re-test.
Markup also plays well with the rest of your technical SEO. A canonical tag tells crawlers which version of a URL is authoritative; if you maintain one, you can pair the canonical habit with structured data discipline by following the canonical link from our canonical tag guide and applying JSON-LD only on that canonical URL. Similarly, a clean meta description and Open Graph block improve how the page is previewed elsewhere; the patterns in our meta tags guide cover the surrounding head section so your markup, metadata, and canonical signals all agree.
What Schema Markup Cannot Do
It is worth setting expectations clearly. Schema markup does not guarantee a rich result, does not bypass quality rules, and does not promote content that is thin, duplicate, or off-topic. It also does not replace good on-page writing. What it does is remove ambiguity. When a crawler can read that a page is a specific kind of Article written by a specific author on a specific date, it can place that page into richer layouts than a plain blue link. The page still has to earn the click.
Used carefully, JSON-LD gives you a precise, vocabulary-defined way to describe your pages to search engines. Generate it from facts that are already on the page, place it correctly, validate the live URL, and your structured data will quietly do its job in the background.
For a deeper look, see How to Extract Every URL From a Website Sitemap.