Operational article · published
Build an Organization Entity Graph for a Service Business
Build a service-business entity graph with stable Organization, WebSite, WebPage, and Service IDs. Includes a downloadable JSON-LD example and validation checks.
Reviewed 2026-09-14 · National guidance, Austin proofThe task and the failure mode
Built for: Developers and site owners connecting a real service business to its website and service pages without inventing locations, credentials, or social profiles.
A business, its website, and a service page are different things. Markup becomes confusing when each template invents a new organization or gives a service the website’s identity. Start with four nodes and explicit relationships. The downloadable example uses a fictional business at example.com; replace it with verified facts before publication. The goal is a consistent description of the business, not a promise of rankings or AI citations.
Decision brief
Use one stable Organization identifier for the same business across the site. In the example it is https://example.com/#organization. Reuse that identifier when a service names its provider or a website names its publisher. Do not generate a different business identity for every service, city, or page template.
Give the WebSite, WebPage, and Service separate identifiers. A WebPage describes the document; a Service describes what is offered. Connect the document to the site with isPartOf and to the service with mainEntity. Connect the service to the business with provider. These references make the intended relationships explicit.
Publish only properties that have a factual basis and appropriate visible support. A social URL belongs in sameAs only when it identifies the same organization, not a loosely related directory or the founder’s personal account. Leave an uncertain address or accreditation out until the responsible person verifies it.
Questions to answer before changing the system
- 01Which organization actually provides the service, and is that identity stated on the page?
- 02Does the existing CMS already emit an Organization node with a reusable identifier?
- 03Which URLs are canonical, and will their identifiers remain stable after a redesign?
- 04Can a visitor verify each name, service, location, and relationship in the visible site?
- 05Does a validator see the same graph in the initial HTML and the rendered page?
Workflow
- 01Inventory the existing output before adding a plugin or component. Inspect the homepage and one service page for application/ld+json scripts. Record their types, identifiers, publisher references, and provider references. Two valid JSON objects can still disagree about which organization runs the website.
- 02Write a short identity map. Assign /#organization to the business, /#website to the site, /services/drain-cleaning#webpage to the document, and /services/drain-cleaning#service to its offering. These are example identifiers, not required spellings. Choose one convention and keep it stable across templates.
- 03Download the example and replace its fictional name and domain. The four-node graph shows WebSite.publisher pointing to Organization, WebPage.isPartOf pointing to WebSite, WebPage.mainEntity pointing to Service, and Service.provider pointing back to Organization. Follow each reference and verify that it reaches the intended node.
- 04Match the service node to visible content. The service name and URL should describe the actual offer on that page. Add optional fields only when the business can substantiate them. Do not copy sample reviews, invented opening hours, or an office address merely to make the graph look more complete.
- 05Render the JSON-LD through the existing site template. Serialize a data object rather than constructing JSON through fragile string concatenation. If values can contain user-controlled text, use the framework’s safe serialization approach and prevent an embedded closing script tag from escaping the script element.
- 06Validate at two levels. Use a Schema.org validator for vocabulary and graph structure; use Google’s Rich Results Test for supported Google features. Check required properties for the particular feature you intend to support. A valid generic Service node does not imply that Google offers a Service rich result.
- 07Check the deployed HTML, not only the development object. Confirm the intended canonical, visible service answer, valid JSON, stable identifiers, and working references after hydration. Save the tested URL and release identifier. Recheck another service page to catch template-wide duplication or mismatched providers.
Evidence to retain
- An identity map listing each node, its identifier, its meaning, and the component responsible for rendering it.
- Visible homepage or about-page text supporting the business name and its relationship to the site.
- The service page’s visible offer and canonical URL, compared with the Service and WebPage nodes.
- An inventory of existing CMS and plugin output showing that a second conflicting organization was not introduced.
- Validator results saved with the input version and date, distinguishing syntax errors from unsupported rich-result expectations.
- A raw and rendered HTML check confirming that client navigation does not replace the correct graph with another page’s data.
- A post-release review of at least one additional service URL using the same provider identifier and its own document identity.
Fictional example: Sample Drain Company
- Organization
- https://example.com/#organization identifies Sample Drain Company, the business. It is not a separate city branch or a page.
- WebSite
- https://example.com/#website identifies the site. Its publisher references /#organization rather than repeating an independently generated business.
- WebPage
- /services/drain-cleaning#webpage identifies the service document. isPartOf references /#website and mainEntity references the Service node.
- Service
- /services/drain-cleaning#service describes drain cleaning. Its provider references /#organization and its url points to the visible service page.
- Acceptance
- All four identifiers are distinct, every local reference resolves, and the visible page supports the stated offer. This validates the example structure, not a ranking outcome.
Entity graph release checks
- The real business is identifiable in visible text.
- The fictional example name and example.com domain have been replaced.
- Organization and WebSite use different identifiers.
- Each service and its document have distinct identities.
- The website publisher resolves to the intended organization.
- The service provider references that same organization.
- The document belongs to the correct website.
- No invented office, review, credential, or affiliation was added.
- Existing plugins do not emit contradictory identities.
- Direct navigation and client navigation retain correct page-specific output.
What to measure—and what it does not prove
- Count validated templates rather than the raw number of schema properties. A larger graph can contain more contradictions.
- Track unresolved identity references and duplicate organization identifiers as implementation defects with an owner and a tested URL.
- Check Google-supported feature eligibility separately from generic vocabulary validation. Record warnings without converting them into traffic forecasts.
- Compare later search and lead outcomes against a dated baseline. Other page changes and search conditions can contribute to any movement.
Boundaries and caveats
The downloadable JSON is an instructional example, not the live structured data for VOID or a client.
A graph cannot substitute for useful service information, credible business evidence, or working contact paths.
Use a more specific organization type only when it accurately describes the business; do not invent a storefront.
A successful validator does not guarantee a rich result, an AI mention, indexing, or improved rankings.
Primary sources
- Google Search Central: Organization structured datadevelopers.google.com
- Google Search Central: Structured data policiesdevelopers.google.com
- Schema.org: Organizationschema.org
- Schema.org: WebSiteschema.org
- Schema.org: WebPageschema.org
- Schema.org: Serviceschema.org
Start with one bounded case
Inspect the current JSON-LD on one real service page and compare its identifiers with the downloadable example. Fix one demonstrated identity or relationship error, validate the deployed result, and check a second page before extending the change to every template.