Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a mainEntity property that relates a page to the main thing it describes + inverseOf mainEntityOfPage #301

Closed
danbri opened this issue Jan 29, 2015 · 37 comments
Assignees
Labels
guidelines docs examples Work on our supporting materials rather than on schema definitions schema.org vocab General top level tag for issues on the vocabulary status:work expected We are likely to, or would like to, or probably should try, ... to do something in this area.

Comments

@danbri
Copy link
Contributor

danbri commented Jan 29, 2015

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. Sometimes metadata (including inbound links) exploits the obvious association between page and the thing it describes, even blurring the distinction between the two.

The proposal here is to add a new property, 'mainEntity' which is a relationship between a document and the main thing that it describes.

Update: Feb5th based on discussion below and other feedback, am proposing also adding an inverseOf mainEntity, mainEntityOfPage.

Goals

  • Given a page, potentially describing several different things using schema.org, it should be very easy to determine which thing/entity is the 'main' one that it describes.

Non-Goals

  • Resolving https://en.wikipedia.org/wiki/HTTPRange-14
  • Specifying exactly when it is ok to use 'url' of a page when really we're talking about the underlying real world entity, e.g. using http://www.imdb.com/name/nm0000136/ to stand for Johnny Depp.
  • Addressing vaguer notions of aboutness such as topics ("social policy in Manchester after 1965"), or situations such as list/category pages where the document is about a collection of things (although ItemList may be useful here for some scenarios).
  • Requiring every page to say what it is about. While it is useful to be able to mention a mainEntity (at least to have the terminology defined to do so), it is also not likely to be required every time schema.org is being used to describe something.

Examples

A Restaurant homepage (in Microdata)

Taking an existing example of http://schema.org/Restaurant and expanding:

<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>

A MusicGroup described in page alongside related entities (e.g. JSON-LD)

  • A page such as https://musicbrainz.org/artist/650e7db6-b795-4eb5-a702-5ea2fc46c848 is primarily about a MusicGroup whose name is "Lady Gaga" (see embedded JSON-LD)
  • It records many other facts about her, using several different schema.org types.
  • Alongside the main entity, the MusicGroup "Lady Gaga", there are several subsidiary entities mentioned; e.g. musical aspects such as a MusicAlbum or MusicRecording; as well as AdministrativeArea, Country, City etc., perhaps Events too.
  • How can we tell which is the main focus of the page? We look for a mainEntity relationship pointing to the entity from the page. Other approaches that might seem reasonable, like taking the first, top-most or outer entity are fragile and do not work well with extraction techniques (e.g. any23) and all RDF tooling, which abstract away from concrete syntax.
  • In JSON-LD this could be written using @Rev syntax to nest a link to the page URL inside a description of the MusicGroup, or wrapped around the MusicGroup. Different variations will make sense on different sites, depending on how their markup and data are structured.

Questions

  • Is mainEntity inverseOf the url property? Maybe...
  • Is this the same as foaf:primaryTopic? Yes.
  • 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...
  • Will this help close the gap between schema.org and Open Graph Protocol (OGP)? Potentially, yes.

Alternatives that do not work (for the purposes above)

  • The http://schema.org/mainContentOfPage property, which relates a WebPage to a WebPageElement, is superficially similar. However its values are presented as parts of the page, rather than the real world things described by that markup. It also has a long, unwieldy name. see also Expand the range of 'mainContentOfPage' to Thing #215
  • Re-using the 'about' property. Since 2011 this property has allowed multiple values. For the mainEntity it is important that at most one value is allowed (i.e. it is a "functional property") (see retracted proposal from @danbri )
  • Having mainEntity be a boolean property. Although it might be simpler to write mainEntity='true' or , the information we are recording is intrinsically related to the page carrying it.
@danbri danbri added schema.org vocab General top level tag for issues on the vocabulary guidelines docs examples Work on our supporting materials rather than on schema definitions status:needs review status:work expected We are likely to, or would like to, or probably should try, ... to do something in this area. labels Jan 29, 2015
@danbri danbri self-assigned this Jan 29, 2015
@danbri danbri added this to the 2015 Q1 milestone Jan 29, 2015
@danbri
Copy link
Contributor Author

danbri commented Jan 29, 2015

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

@thadguidry
Copy link
Contributor

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..

@jasondouglas
Copy link

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.

@niklasl
Copy link

niklasl commented Jan 29, 2015

+1 for the proposal. Suggested addition:

schema:mainEntity rdfs:subPropertyOf schema:about .

@westurner
Copy link
Contributor

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?

@danbri
Copy link
Contributor Author

danbri commented Jan 29, 2015

@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?

@jasondouglas
Copy link

@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).

@danbri
Copy link
Contributor Author

danbri commented Jan 29, 2015

@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.

@danbri
Copy link
Contributor Author

danbri commented Jan 29, 2015

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.

@sesuncedu
Copy link
Contributor

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.

@jasondouglas
Copy link

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).

@danbri
Copy link
Contributor Author

danbri commented Jan 29, 2015

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.

@sesuncedu
Copy link
Contributor

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

@gkellogg
Copy link
Contributor

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": "#"}, ...)

@jvandriel
Copy link

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

@danbri danbri changed the title Add a mainEntity property that relates a page to the main thing it describes Add a mainEntity property that relates a page to the main thing it describes + inverseOf mainEntityOfPage Feb 5, 2015
@danbri
Copy link
Contributor Author

danbri commented Feb 5, 2015

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.

@danbri
Copy link
Contributor Author

danbri commented Feb 6, 2015

An example,

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> .

@vholland
Copy link
Contributor

vholland commented Feb 6, 2015

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

@danbri
Copy link
Contributor Author

danbri commented Feb 6, 2015

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>

@sesuncedu
Copy link
Contributor

sesuncedu commented Feb 6, 2015 via email

@jvandriel
Copy link

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

danbri added a commit that referenced this issue Mar 16, 2015
danbri added a commit that referenced this issue Mar 16, 2015
@jvandriel
Copy link

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.

@mfhepp
Copy link
Contributor

mfhepp commented Apr 16, 2015

+1

@danbri
Copy link
Contributor Author

danbri commented Apr 16, 2015

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.

@Aaranged
Copy link

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".

@danbri danbri modified the milestones: sdo-gozer release, 2015 Q1 Apr 17, 2015
@danbri
Copy link
Contributor Author

danbri commented Apr 17, 2015

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

@jvandriel
Copy link

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>

@Aaranged
Copy link

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

@tmarshbing
Copy link

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.

@danbri
Copy link
Contributor Author

danbri commented Apr 25, 2015

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).

danbri added a commit that referenced this issue Apr 29, 2015
@danbri danbri closed this as completed in 3354c5c Apr 29, 2015
@danbri
Copy link
Contributor Author

danbri commented Apr 29, 2015

@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.

@danbri
Copy link
Contributor Author

danbri commented Apr 29, 2015

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.

@niklasl
Copy link

niklasl commented Apr 29, 2015

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.

@jvandriel
Copy link

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).

@jvandriel
Copy link

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.

@danbri
Copy link
Contributor Author

danbri commented May 6, 2015

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>

@Ezra-Siton-UIX
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
guidelines docs examples Work on our supporting materials rather than on schema definitions schema.org vocab General top level tag for issues on the vocabulary status:work expected We are likely to, or would like to, or probably should try, ... to do something in this area.
Projects
None yet
Development

No branches or pull requests