Schema.org practices for small company: 'Organization' and 'WebSite' in JSON-LD on every page, Microdata for everything else

Question

I'm wondering how to build my Schema.org. I'm using mixed approach with both JSON-LD and Microdata elements. I don't use them to describe one thing in 2 different ways. I need some guidelines about what to include.

For now I have description of our company on every page:

<script type="application/ld+json">
{
    "@context"          : "http://schema.org",
    "@type"             : "Organization",
    "url"               : "https://our.url",
    "logo"              : "https://our.url/logo2.svg",
    "contactPoint"      : [{
        "@type"         : "ContactPoint",
        "telephone"     : "",
        "contactType"   : "Customer Service"
    }],
    "sameAs"            :[],
    "name"              : "Our Small Company"
}
</script>

Than I have a small description of our webpage again in JSON-LD:

<script type="application/ld+json">
{
   "@context"          : "http://schema.org",
    "@type"             : "WebSite",
    "url"               : "http://our.url",
    "potentialAction"   : {
        "@type"         : "SearchAction",
        "target"        : "http://our.url/search",
        "query-input"   : "required name=search_term_string"
    }
}
</script>

And from here after I have Microdata for all elements. For example search results are ItemList with products, etc.

Does this seem Ok? Should I include JSON-LD company description on every page or only on the home page or not at all? Do I need to dig down and provide more specific description for every page (for example search page could be SearchResultsPage instead of WebSite)?

Answer 1

Providing some data in JSON-LD and some data in Microdata should be fine (but if both were about the same entities, you should denote this explicitly). It can become problematic if you want to connect the entities, though.

Connecting WebSite and Organization

Speaking of connecting entities, I would recommend to do this for your WebSite and Organization items. For example, you could state that your Organization is the publisher of the WebSite, and/or that the WebSite is about the Organization.

There are two ways how to achieve this in JSON-LD:

• use one script element and embed the Organization node as value
• keep both script elements (or one script element with @graph), give each node a URI (with @id) and reference these URIs as values

The former probably has better consumer support, the latter makes it more suitable to provide multiple properties (e.g., author and publisher) without having to duplicate the whole data (but you could use a mixed way, too).

Example for the former way:

<script type="application/ld+json">
{
   "@context"          : "http://schema.org",
   "@type"             : "WebSite",
   "publisher"         : {
       "@type"         : "Organization"
   }
}
</script>

Example for the latter way:

<script type="application/ld+json">
{
    "@context"          : "http://schema.org",
    "@type"             : "Organization",
    "@id"               : "/#org"
}
</script>

<script type="application/ld+json">
{
    "@context"          : "http://schema.org",
    "@type"             : "WebSite",
    "publisher"         : {"@id": "/#org"},
    "about"             : {"@id": "/#org"},
    "mainEntity"        : {"@id": "/#org"},
    "author"            : {"@id": "/#org"}
}
</script>

(where /#org is the URI that represents the organization itself, not just a page/site about or of the organization)

Providing WebPage

You can provide a WebPage item for each page. It can be helpful in many situations. But like it’s the case with any other type, too, there is no requirement whatsoever.

If you want to provide such an item, using the more specific types (like SearchResultsPage) where applicable is of course preferable. But if that’s not possible, using WebPage everywhere is way better than not providing it all.

In your case, you would have to decide in which syntax to provide it. JSON-LD would allow you to provide it as hasPart of the WebSite according to the former way, as explained above. But that would make it hard to connect the WebPage with your page’s main entity (which you specify in Microdata) via the mainEntity property. As I think this is an important relation, I would specify the WebPage in Microdata and connect the WebSite and the WebPage via URIs.

You could do this from the JSON-LD WebSite node with:

"hasPart"           : {"@id": "/current-page.html"}

(You could also do this from the WebPage Microdata with the inverse property isPartOf, but then you’d have to provide an @id for the WebSite.)

Having the WebPage in Microdata, e.g., on the body element, it allows you to provide the mainEntity property:

<body itemscope itemtype="http://schema.org/WebPage">
  <article itemprop="mainEntity" itemscope itemtype="http://schema.org/Article">
    <!-- for an article that is the main content of the page -->
  </article>
</body>

<body itemscope itemtype="http://schema.org/SearchResultsPage">
  <ul itemprop="mainEntity" itemscope itemtype="http://schema.org/ItemList">
    <!-- for a search result list that is the main content of the page -->
  </ul>
</body>

Connecting WebPage and Organization

If you prefer, you could explicitly state that the Organization is the publisher/author/etc. of the WebPage, too:

<link itemprop="author publisher" href="/#org" />

(It could be deduced because you state this for the WebSite and every WebPage is connected via hasPart, but this is probably too advanced for many consumers, so stating it explicitly could help.)