Another use case: using tools that return a graph, knowing the mainEntity gives you a useful entry point into a complex linked data structure.

Would supplying an 'url' property indicating the current page be an adequate alternate expression of 'mainEntity'? Not sure - let's discuss. The use of 'url' varies quite a lot in practice...

That sounds like a loopback that does not solve the problem "the mainEntity on this page is SOMEWHERE on this same page?!?!?" WTF ?

+1 for mainEntity. I think it is clear and we know what we want to accomplish. I see very little argument against or change the proposal. The examples make sense. I like the @rev wrapping method for JSON-LD as well - let's be sure to find a way to document for those coming into the microdata example that there is a JSON-LD way as well (and vice-versa), and point them to a good JSON-LD example that uses @rev..

I think it's a requirement that you be able to refer to the main entity in markup on other pages by the canonical URL of that leaf page. However, in your example, it's the WebPage entity that gets the canonical URL.

+1 for the proposal. Suggested addition:

schema:mainEntity rdfs:subPropertyOf schema:about .

schema:mainEntity rdfs:subPropertyOf schema:about .

seems to make sense?

How to avoid terminological overlap with rdf:subject?

Looking at http://topbraid.org/schema/ , how would schema:mainEntity be distinct from schema:url?

@jasondouglas hopefully we can define the property without requiring global agreement on URL use. But would a tweak to the example that gave the WebPage entity a trivially different URL help? (in this example one ending with a final '#' ):

Microdata:

<div itemid="#" itemscope itemtype="http://schema.org/WebPage">
    <div itemprop="mainEntity" itemscope itemtype="http://schema.org/Restaurant">
      <h1 itemprop="name">Fondue for Fun and Fantasy</h1>
      <p itemprop="description">Fantastic and fun for all your cheesy occasions.</p>
      <p>Open: <time itemprop="openingHours" datetime="Mo,Tu,We,Th,Fr,Sa,Su 11:30-23:00">Daily from 11:30am till 11pm</time></p>
      <p>Phone: <span itemprop="telephone" content="+155501003333">555-0100-3333</span></p>
      <p>View <a itemprop="menu" href="http://example.com/menu">our menu</a>.</p>
    </div>
</div>

RDFa:

<div resource="#" vocab="http://schema.org/" typeof="WebPage">
    <div property="mainEntity" typeof="http://schema.org/Restaurant">
      <h1 property="name">Fondue for Fun and Fantasy</h1>
      <p property="description">Fantastic and fun for all your cheesy occasions.</p>
      <p>Open: <time property="openingHours" datetime="Mo,Tu,We,Th,Fr,Sa,Su 11:30-23:00">Daily from 11:30am till 11pm</time></p>
      <p>Phone: <span property="telephone" content="+155501003333">555-0100-3333</span></p>
      <p>View <a property="menu" href="http://example.com/menu">our menu</a>.</p>
    </div>
</div>

JSON-LD:

<script type="application/ld+json">    
{ 
    "@context": "http://schema.org", "@id": "#",
    "mainEntity": 
    {
      "@type": "Restaurant",
      "name": "Fondue for Fun and Fantasy",
      "description": "Fantastic and fun for all your cheesy occasions",
      "openingHours": "Mo,Tu,We,Th,Fr,Sa,Su 11:30-23:00",
      "telephone": "+155501003333",
      "menu": "http://example.com/menu"
    }
}
</script>

If mainEntity is a link between different things (a doc and the entity) they'll need different identifiers. It seems much easier to agree that having such a property is useful than to persuade millions of sites to choose a particular pattern for assigning URLs. Do you have a preferred best practice that should be encouraged?

@danbri I think focusing on the inverted relationship is more intuitive:

<div vocab="http://schema.org/" "typeof="http://schema.org/Restaurant">
  <link property="mainEntityOfPage" href="#">  <!-- or maybe this should just be boolean? -->
  <h1 property="name">Fondue for Fun and Fantasy</h1>
  <p property="description">Fantastic and fun for all your cheesy occasions.</p>
  <p>Open: <time property="openingHours" datetime="Mo,Tu,We,Th,Fr,Sa,Su 11:30-23:00">Daily from 11:30am till 11pm</time></p>
  <p>Phone: <span property="telephone" content="+155501003333">555-0100-3333</span></p>
  <p>View <a property="menu" href="http://example.com/menu">our menu</a>.</p>
</div>

You could complain about uniqueness, but that's an issue with any approach (I can specify multiple values for mainEntity too).

@jasondouglas I toyed with those designs too. I think we're close. How about adding the relation named in both directions (mainEntity and mainEntityOfPage), but having the relationship to a document being the preferred usage. Whether the boolean fallback option works depends on processing scenarios - e.g. if you're merging triples from several such documents you might be out of luck.

I'm not worried about enforcing uniqueness, people will always mess up until there are tools and incentives that help them do a cleaner job.

I had a look at @reverse in JSON-LD. It isn't especially pretty for this, and helps makes @jasondouglas 's case to name the relationship in the other direction:

<script type="application/ld+json">    
{ 
    "@context": "http://schema.org",
    "@type": "Restaurant",
    "@reverse": { "mainEntity": { "@id": "#"}},
    "name": "Fondue for Fun and Fantasy",
    "description": "Fantastic and fun for all your cheesy occasions",
    "openingHours": "Mo,Tu,We,Th,Fr,Sa,Su 11:30-23:00",
    "telephone": "+155501003333",
    "menu": "http://example.com/menu"
}
</script>

(if the schema.org JSON-LD file declared mainEntity as taking id values I think this could just be "@reverse": { "mainEntity": "#"}, ...)

mainEntityOfPage would then mean much the same as foaf:isPrimaryTopicOf, i.e. it "relates something to a document that is mainly about it.".

I wonder whether the "Page" part is worthwhile -- e.g. podcasts, broadcasts, .avi files might all also have main entities.

I spent too much time working in this space at the graduate level to be
even able to understand the title of this issue 😱

However, there does seem to be a possible question how such a property
might interact with schema:sameAs.

I've been treating that property as being roughly equivalent to the OWL
axiom

HasKey(schema:Thing (schema:sameAs) ())

This is basically ignoring the contents of the web page (WebPage?) ; the
existence of a mainEntity property for the page would seem to make the
value of that property be = to anything that has a sameAs of that page,
and thus might seem to require the page to be dereferenced for equality
reasoning.

I'm sure everything will go wrong because blank nodes.

Huh, that makes me wonder if we're overthinking this. Could it just
sufficient to declare the itemid to be the same as the URL of the webpage
and be done with it? No declaration of the WebPage itself or other
properties. Much simpler.

On Thu Jan 29 2015 at 12:47:08 PM Simon Spero notifications@github.com
wrote:

I spent too much time working in this space at the graduate level to be
even able to understand the title of this issue 😱

However, there does seem to be a possible question how such a property
might interact with schema:sameAs.

I've been treating that property as being roughly equivalent to the OWL
axiom

HasKey(schema:Thing (schema:sameAs) ())

This is basically ignoring the contents of the web page (WebPage?) ; the
existence of a mainEntity property for the page would seem to make the
value of that property be = to anything that has a sameAs of that page,
and thus might seem to require the page to be dereferenced for equality
reasoning.

I'm sure everything will go wrong because blank nodes.

—
Reply to this email directly or view it on GitHub
#301 (comment).

Intriguing, though I don't know whether people responsible for content payload will always be in a position to ensure the CMS or whatever doesn't add WebPage properties for the document itself.

The test for overthinking on this is whether you can't remember if you
meant to talk about Patrick Winston or Patrick Wilson ;-)

On Jan 29, 2015, at 12:10 PM, Dan Brickley notifications@github.com wrote: "I had a look at @reverse https://github.com/reverse in JSON-LD. It isn't especially pretty for this, and helps makes @jasondouglas https://github.com/jasondouglas 's case to name the relationship in the other direction [...]"

We did at @itemprop-reverse to Microdata (experimentally, anyway) for
exactly this purpose. The json-ld @reverse can be hidden in a term
definition.

(if the schema.org JSON-LD file declared mainEntity as taking id values I
think this could just be "@reverse https://github.com/reverse": {
"mainEntity": "#"}, ...)

+1 for the proposal (as if I could be against it, hehe)

I've updated the description above to include in the proposal a property named in the opposite direction, mainEntityOfPage. Although it might seem decadent and redundant having both directions, we do this sometimes in schema.org where the information is particularly useful, on the basis of our rule of thumb which is to make things easier for publishers even if it makes things slightly harder for consumers.

An example,

• http://www.bbc.co.uk/programmes/b03gg84h
  • Google extraction: https://developers.google.com/webmasters/structured-data/testing-tool/?url=http://www.bbc.co.uk/programmes/b03gg84h
  • Ivan's RDFa parser extraction: http://www.w3.org/2012/pyRdfa/extract?uri=http%3A%2F%2Fwww.bbc.co.uk%2Fprogrammes%2Fb03gg84h&format=turtle&rdfagraph=output&vocab_expansion=false&rdfa_lite=false&embedded_rdf=true&space_preserve=true&vocab_cache=true&vocab_cache_report=false&vocab_cache_refresh=false

Excerpt from data shows 3 RadioEpisode entities. But which one is the single primary focus of the page?

<http://www.bbc.co.uk/programmes/b03gg84h> a ns2:RadioEpisode;
    og:description "Steve's guests are Great British Bake Off judge Paul Hollywood and conductor John Wilson."@en-gb;
    og:image "http://ichef.bbci.co.uk/images/ic/368x207/p01lb3vw.jpg"@en-gb;
    og:site_name "BBC"@en-gb;
    og:title "Paul Hollywood and John Wilson, Steve Wright in the Afternoon - BBC Radio 2"@en-gb;
    og:type "website"@en-gb;
    og:url "http://www.bbc.co.uk/programmes/b03gg84h"@en-gb;
    ns2:description "Steve and the team chat to Great British Bake Off judge Paul Hollywood and conductor John Wilson, and there's more fascinating Factoids and your Non-Stop Oldies. Plus the latest lifestyle and entertainment news and an afternoon of amazing music."@en-gb;
    ns2:image "http://ichef.bbci.co.uk/images/ic/544x306/p01lb3vw.jpg"@en-gb;
    ns2:name "Paul Hollywood and John Wilson"@en-gb;
    ns2:partOfSeries <http://www.bbc.co.uk/programmes/b006wr4r>;
    ns2:publication [ a ns2:BroadcastEvent;
            ns2:publishedOn <http://www.bbc.co.uk/radio2>;
            ns2:startDate "2013-11-04T14:00:00+00:00"^^xsd:dateTime ];
    ns2:timeRequired "PT10620S"@en-gb;
    ns3:usesVocabulary ns2: .

<http://www.bbc.co.uk/programmes/b03gg9mf> a ns2:RadioEpisode;
    ns2:name "Frank Skinner, Gareth Malone, Kevin Kennedy"@en-gb;
    ns2:url <http://www.bbc.co.uk/programmes/programmes/b03gg9mf> .

<http://www.bbc.co.uk/programmes/b03fflnx> a ns2:RadioEpisode;
    ns2:name "Sanjeev Bhaskar and Fred Dinenage"@en-gb;
    ns2:url <http://www.bbc.co.uk/programmes/programmes/b03fflnx> .

It's not marked up as so, but wouldn't the RadioSeries "Steve Wright in the Afternoon" be the main topic?

The series is marked up via:
"partOfSeries http://www.bbc.co.uk/programmes/b006wr4r;

I'd read this as that http://www.bbc.co.uk/programmes/b006wr4r is mostly about that series, whereas http://www.bbc.co.uk/programmes/b03gg84h and http://www.bbc.co.uk/programmes/b03fflnx are mostly about specific episodes in that series.

The Series page i.e. http://www.bbc.co.uk/programmes/b006wr4r has this:

<div vocab="http://schema.org/" typeof="RadioSeries" 
    resource="http://www.bbc.co.uk/programmes/b006wr4r"> 
    <h1 property="name">Steve Wright in the Afternoon</h1>
    <meta property="image" content="http://ichef.bbci.co.uk/images/ic/480x270/p01lcfl4.jpg" />
    <div property="description">
        <p>Steve Wright's afternoon show with special guests, music and a host of other features</p>
    </div>  
...</div>

Another example can be found on: http://www.imdb.com/title/tt1617661/, which contains 3 Top Level Entities: Movie, VideoObject and another VideoObject.

Google's SDTT: https://developers.google.com/webmasters/structured-data/testing-tool/?url=http://www.imdb.com/title/tt1617661/?ref_=inth_ov_tt

Is there any chance sponsors will make an announcement when either of 'm is ready to support mainEntity/mainEntityOfPage?

IMHO this is one of those cases where the sponsors should provide support before there are enough use cases as one my biggest worries is that folks won't start using it if they notice that it prevents them from getting enriched search result snippets.

+1

At this point, sdo-gozer should be considered a work-in-progress (and in flux). Things that are in gozer but not yet in schema.org may continue to evolve as we talk things through, get wider review, yadda yadda. Whether and when search engines make use of the vocabulary is another matter.

Suggestion for the example/examples when this eventually released based on the current example at http://sdo-gozer.appspot.com/mainEntity.

Namely, that two entities should be present. That is, would there any reason to declare "the primary entity described in some page or other CreativeWork" if there were no other entities described? Both "main" and "primary" infer the existence of "secondary".

Filing this for gozer. We're nearly there with it.

I agree with you @Aaranged - would this work for you?

mainEntityOfPage

<body itemid="http://www.example.com/about-acme-corporation" itemscope itemtype="http://schema.org/AboutPage">
    <main>
        <article itemscope itemtype="http://schema.org/Article">    
            <h1 itemprop="name">About Acme Corporation</h1>

            <p itemprop="description">...</p>

            <div itemprop="articleBody">
                <p>...</p>
            </div>

            <aside itemprop="about" itemscope itemtype="http://schema.org/Corporation">
                <h2 itemprop=name>Acme Anvil Corporation</h2>
                <meta itemprop="alternateName" content="Acme Corporation">

                <link itemprop="mainEntityOfPage" href="http://www.example.com/about-acme-corporation">

                <p>
                    <figure itemprop="logo" itemscope itemtype="http://schema.org/ImageObject">
                        <img itemprop="contentUrl" src="http://www.example.com/media/acme-anvil-corporation.jpg" alt="Acme Anvil Corporation">
                        <figcaption itemprop="caption">preferred by blacksmiths and coyotes</figcaption>
                    </figure>

                    <a itemprop="sameAs" href="http://en.wikipedia.org/wiki/Acme_Corporation" title="about Acme Corporation">More on Wikipedia</a>
                </p>
            <aside>
        </article>
    </main>
</body>

mainEntity

<body itemid="http://www.example.com/about-acme-corporation" itemscope itemtype="http://schema.org/AboutPage">
    <main>
        <article itemscope itemtype="http://schema.org/Article">    
            <h1 itemprop="name">About Acme Corporation</h1>

            <link itemprop="about" href="#acme-anvil-corporation">

            <p itemprop="description">...</p>

            <div itemprop="articleBody">
                <p>...</p>
            </div>
        </article>

        <aside id="acme-anvil-corporation" itemid="#acme-anvil-corporation" itemprop="mainEntity" itemscope itemtype="http://schema.org/Corporation">
            <h2 itemprop=name>Acme Anvil Corporation</h2>
            <meta itemprop="alternateName" content="Acme Corporation">

            <p>
                <figure itemprop="logo" itemscope itemtype="http://schema.org/ImageObject">
                    <img itemprop="contentUrl" src="http://www.example.com/media/acme-anvil-corporation.jpg" alt="Acme Anvil Corporation">
                    <figcaption itemprop="caption">preferred by blacksmiths and coyotes</figcaption>
                </figure>

                <a itemprop="sameAs" href="http://en.wikipedia.org/wiki/Acme_Corporation" title="about Acme Corporation">More on Wikipedia</a><br>
            </p>
        <aside>
    </main>
</body>

Thanks @jvandriel - both these and the revised gozer examples are much clearer.

Should we have some longer description somewhere about proper usage of mainEntity v. sameAs v. about v. url? Something along the lines of the below, using the initial description from @danbri above as a start? Also, is there an existing mechanism to specify the cardinality of the properties so that we can say that mainEntity should be single-valued, while mainEntityOfPage can be multi-valued? Or do we rely on the property descriptions for that?

Draft longer description (to be put in documentation somewhere?):

Many (but not all) pages have a fairly clear primary topic, some entity or thing that the page describes. For example a restaurant's home page might be primarily about that Restaurant, or an event listing page might represent a single event. The mainEntity and mainEntityOfPage properties allow you to express the relationship between the page and the primary entity.

Related properties include sameAs, about, and url.

sameAs and url are both similar to mainEntityOfPage, but sameAs and url should be reserved to refer to more official or authoritative web pages, such as the item’s Wikipedia page or official website. mainEntityOfPage can be used for any page, including those not recognized as the authoritative for the entity. For example, for a product, sameAs might refer to a page on the manufacturer’s official site with specs for the product, while mainEntityOfPage might refer to pages on various retailers’ sites with details for the same product.

about is similar to mainEntity, with two key differences. First, about can refer to multiple entities/topics, while mainEntity should be used for only the primary one. Second, some pages have a primary entity that itself describes some other entity. For example, one web page may display a news article about a particular person. Another page may display a product review for a particular product. In these cases, mainEntity for the pages should refer to the news article or review, respectively, while about would more properly refer to the person or product.

Thanks @tmarshbing - I think you're right, this deserves a more careful write up. I would be fine including something like this in the term's main description (too?). We might also mention or include it in docs/datamodel.html (which could also do with a refresh).

@tmarshbing - I've added most of your text into http://sdo-gozer.appspot.com/mainEntityOfPage (tweaked a bit near the start to distinguish sameAs vs url slightly differently). The property names need hyperlinking, but apart from that I think it is an improvement. I'm marking this as closed (ever optimistic) but please re-open or comment here if more is needed.

It has also been suggested that we should allow a simple boolean value, e.g. on some page it might say mainEntityOfPage: "true", as a property of the entity. This doesn't work well when asserted in a different page but could be a reasonable shorthand.

Looks good. I believe the introductory text on http://sdo-gozer.appspot.com/mainEntityOfPage is suitable for both properties. The latter part is about mainEntity and should be moved to its corresponding page.

If I might make a suggestion, how about something like this for the third paragraph:

The url property should be reserved to refer to the webpage where the thing it has been labelled for can be found, whereas the sameAs property relates to webpages that indirectly identify it. The mainEntityOfPage property serves to clarify which of several entities on a webpage is the main one for that page.

I found the current paragraph a bit hard to digest (feel free to reject or modify of course).

An even braver attempt? :)

Related attributes and properties include @itemid, @resource, @id, sameAs, about, and url.

The url property should be reserved to refer to the webpage where the thing it has been labelled for can be found whereas the sameAs property relates to webpages that indirectly identify it. @itemid (microdata), @resource (RDFa) and @id (JSON-LD) can be used to uniquely identify things that are being described on a page. The mainEntityOfPage property serves to clarify which of several entities on a webpage is the main one for that page.

9d1c502 fixes an oversight from the earlier commit. By listing URL as an expected type, we add this property to those declared in our JSON-LD context file i.e. http://sdo-gozer.appspot.com/docs/jsonldcontext.json as defaulting to @id types. This means we can have a more convenient shorthand for relative URLs.

<script type="application/ld+json">
{
    "@context": "http://schema.org",
      "@type": "Restaurant",
      "mainEntityOfPage": { "@id": "" },
      "name": "Cath's Cafe",
      "openingHours": "Mo,Tu,We,Th,Fr,Sa,Su 11:00-20:00",
      "telephone": "+155501003344",
      "menu": "/menu"
}
</script>

Can now be,

<script type="application/ld+json">
{
    "@context": "http://schema.org",
      "@type": "Restaurant",
      "mainEntityOfPage": "",
      "name": "Cath's Cafe",
      "openingHours": "Mo,Tu,We,Th,Fr,Sa,Su 11:00-20:00",
      "telephone": "+155501003344",
      "menu": "/menu"
}
</script>

The docs about "mainEntity " is not clear (zero example for something is a little abstract). Please fix this.