Online Tool Store
· 5 min read
How to Map Schema.org Entity Relationships
Manesh Jayawardhana
CIO & Co-founder
You are adding structured data for a local shop. The business has an address, an opening-hours specification, and perhaps a founder or parent organization. Each piece makes sense alone, but the JSON-LD becomes confusing once you must decide which object contains which property and whether an item should be nested or separately identified.
Starting directly in a long script block makes that structural problem harder to see. A small entity-relationship map lets you state one connection plainly—LocalBusiness links through address to PostalAddress—before you translate it into Schema.org markup. It is a planning aid, not a validator, but that visual step can prevent a tidy-looking object with the wrong relationship.
What a Schema.org relationship involves
Schema.org provides types such as Article, Person, Organization, Product, and LocalBusiness, along with properties that describe or connect them. A property may hold a simple value, such as text, or another typed entity. When LocalBusiness.address points to a PostalAddress, the address is more than a loose string: it is an entity with its own fields.
The main entity is the subject you are describing. The linked entity supplies related information, and the relationship property explains how the two connect. Writing those three parts first gives you a sentence you can check against the vocabulary: “This LocalBusiness has an address that is a PostalAddress.”
A single page can contain several such links. An Article may have an author of type Person, and that person may have an affiliation of type Organization. A visualizer that shows one relationship at a time helps you reason through each edge before assembling the larger graph.
| Main Entity | Property | Linked Entity | Practical Meaning |
|---|---|---|---|
LocalBusiness | address | PostalAddress | Where the business is located |
Article | author | Person | Who wrote the article |
Product | brand | Brand | Which brand identifies it |
Person | worksFor | Organization | The person’s employer |
These examples illustrate structure, not a guarantee that every property is appropriate for every page. Always check the current vocabulary and content represented on the page.
Why people get stuck here
The first problem is confusing properties with types. PostalAddress is a type, while address is a property. Putting the type name where a relationship property belongs can produce markup that looks plausible to a person but does not express the expected model.
The second problem is copying examples without matching the page. Structured data should describe visible, genuine content. Adding an entity because it appears in a template—or inventing details to fill recommended fields—creates a mismatch between markup and the page readers see.
Finally, validation happens at more than one level. JSON can be syntactically valid while using an unsuitable Schema.org property. Schema.org-compatible markup can still fail the eligibility rules of a particular search feature. A diagram cannot replace vocabulary review or a rich-results test.
What a good entity map looks like
Each box has a real type
Use exact Schema.org type names and check their capitalization. LocalBusiness and PostalAddress are types; informal labels such as “Shop Details” may be useful in a team diagram but cannot simply be copied into @type.
Each connection reads as a sentence
Say the relationship aloud: “The article’s author is this person.” If Article → author → Person reads naturally and the property supports those values, the eventual JSON-LD structure is easier to defend.
Validation follows visualization
Once the plan is translated to JSON-LD, validate the code separately. This JSON-LD generation guide covers the markup step, while the JSON-LD to microdata guide is useful only when a project specifically requires another serialization.
Common mistakes to avoid
- Entering a display label instead of an exact Schema.org type or property.
- Assuming a visual connection proves that the property supports that entity type.
- Adding entities or claims that are not supported by the page’s visible content.
- Treating valid JSON as proof that structured data is semantically valid.
- Building a large graph before checking each relationship individually.
How to do it with Schema.org Entity Relationship Visualizer
Open the Schema.org Entity Relationship Visualizer to sketch one connection at a time.
- Enter the main entity, such as
LocalBusiness. - Enter the linked entity, such as
PostalAddress. - Enter the relationship property, such as
address. - Select Update map.
- Read the map from the main card, through the labeled connection, to the linked card.
- Confirm the terms in current Schema.org documentation before writing JSON-LD.
The tool runs locally and displays a simple two-entity relationship. It does not generate JSON-LD, verify whether a property is allowed, store multiple connections, or test search-feature eligibility. Use it to make the idea visible, then move to the appropriate documentation and validator.
The online tool directory contains additional code and SEO helpers for the implementation stage.
Frequently asked questions
Should I nest an entity or give it an @id?
Nesting is convenient when the entity belongs only to that context. An @id can help connect the same identifiable entity from several places in a graph. Choose based on the model and keep identifiers stable and absolute where appropriate.
Does this visualizer validate Schema.org terms?
No. It displays the text entered into three fields. Confirm type and property names with current Schema.org documentation, then validate the finished markup using a suitable structured-data tool.
Can it visualize a complete JSON-LD graph?
The current tool shows one main entity, one linked entity, and one relationship property. For a complex graph, map each important relationship separately or use dedicated graph tooling after clarifying the individual connections.
Final thought
Structured data becomes manageable when each connection can be stated in one clear sentence. Map the entity, property, and linked entity first; then write and validate the code with far fewer structural guesses.