{"action":"created","issue":{"url":"https://api.github.com/repos/schemaorg/schemaorg/issues/301","labels_url":"https://api.github.com/repos/schemaorg/schemaorg/issues/301/labels{/name}","comments_url":"https://api.github.com/repos/schemaorg/schemaorg/issues/301/comments","events_url":"https://api.github.com/repos/schemaorg/schemaorg/issues/301/events","html_url":"https://github.com/schemaorg/schemaorg/issues/301","id":55921629,"number":301,"title":"Add a mainEntity property that relates a page to the main thing it describes + inverseOf mainEntityOfPage","user":{"login":"danbri","id":170265,"avatar_url":"https://avatars.githubusercontent.com/u/170265?v=3","gravatar_id":"","url":"https://api.github.com/users/danbri","html_url":"https://github.com/danbri","followers_url":"https://api.github.com/users/danbri/followers","following_url":"https://api.github.com/users/danbri/following{/other_user}","gists_url":"https://api.github.com/users/danbri/gists{/gist_id}","starred_url":"https://api.github.com/users/danbri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/danbri/subscriptions","organizations_url":"https://api.github.com/users/danbri/orgs","repos_url":"https://api.github.com/users/danbri/repos","events_url":"https://api.github.com/users/danbri/events{/privacy}","received_events_url":"https://api.github.com/users/danbri/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/schemaorg/schemaorg/labels/guidelines%20docs%20examples","name":"guidelines docs examples","color":"009800"},{"url":"https://api.github.com/repos/schemaorg/schemaorg/labels/schema.org%20vocab","name":"schema.org vocab","color":"fbca04"},{"url":"https://api.github.com/repos/schemaorg/schemaorg/labels/status:needs%20review","name":"status:needs review","color":"d4c5f9"},{"url":"https://api.github.com/repos/schemaorg/schemaorg/labels/status:work%20expected","name":"status:work expected","color":"5319e7"},{"url":"https://api.github.com/repos/schemaorg/schemaorg/labels/type:%20rough%20proposal%20idea","name":"type: rough proposal idea","color":"d4c5f9"}],"state":"closed","locked":false,"assignee":{"login":"danbri","id":170265,"avatar_url":"https://avatars.githubusercontent.com/u/170265?v=3","gravatar_id":"","url":"https://api.github.com/users/danbri","html_url":"https://github.com/danbri","followers_url":"https://api.github.com/users/danbri/followers","following_url":"https://api.github.com/users/danbri/following{/other_user}","gists_url":"https://api.github.com/users/danbri/gists{/gist_id}","starred_url":"https://api.github.com/users/danbri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/danbri/subscriptions","organizations_url":"https://api.github.com/users/danbri/orgs","repos_url":"https://api.github.com/users/danbri/repos","events_url":"https://api.github.com/users/danbri/events{/privacy}","received_events_url":"https://api.github.com/users/danbri/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/schemaorg/schemaorg/milestones/12","html_url":"https://github.com/schemaorg/schemaorg/milestones/sdo-gozer%20release","labels_url":"https://api.github.com/repos/schemaorg/schemaorg/milestones/12/labels","id":945063,"number":12,"title":"sdo-gozer release","description":"Milestone for the release following sdo-stantz\r\n\r\nSee http://schema.org/docs/releases.html#sdo-gozer\r\n\r\nTest site was at http://sdo-gozer.appspot.com\r\n\r\nDue date is an estimate.","creator":{"login":"danbri","id":170265,"avatar_url":"https://avatars.githubusercontent.com/u/170265?v=3","gravatar_id":"","url":"https://api.github.com/users/danbri","html_url":"https://github.com/danbri","followers_url":"https://api.github.com/users/danbri/followers","following_url":"https://api.github.com/users/danbri/following{/other_user}","gists_url":"https://api.github.com/users/danbri/gists{/gist_id}","starred_url":"https://api.github.com/users/danbri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/danbri/subscriptions","organizations_url":"https://api.github.com/users/danbri/orgs","repos_url":"https://api.github.com/users/danbri/repos","events_url":"https://api.github.com/users/danbri/events{/privacy}","received_events_url":"https://api.github.com/users/danbri/received_events","type":"User","site_admin":false},"open_issues":54,"closed_issues":39,"state":"open","created_at":"2015-01-21T10:29:12Z","updated_at":"2015-04-29T18:56:21Z","due_on":"2015-04-26T23:00:00Z","closed_at":null},"comments":31,"created_at":"2015-01-29T16:27:43Z","updated_at":"2015-04-29T18:56:52Z","closed_at":"2015-04-29T18:56:21Z","body":"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.\r\n\r\nThe proposal here is to add a new property, 'mainEntity' which is a relationship between a document and the main thing that it describes. \r\n\r\n*Update:* Feb5th based on discussion below and other feedback, am proposing also adding an inverseOf mainEntity, mainEntityOfPage.\r\n\r\n## Goals\r\n\r\n* 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.\r\n\r\n## Non-Goals\r\n\r\n* Resolving https://en.wikipedia.org/wiki/HTTPRange-14\r\n* 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.\r\n* 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).\r\n* 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.\r\n\r\n## Examples\r\n\r\n## A Restaurant homepage (in Microdata)\r\n\r\nTaking an existing example of http://schema.org/Restaurant and expanding:\r\n\r\n    <div itemid=\"\" itemscope itemtype=\"http://schema.org/WebPage\">\r\n        <div itemprop=\"mainEntity\" itemscope itemtype=\"http://schema.org/Restaurant\">\r\n          <h1 itemprop=\"name\">Fondue for Fun and Fantasy</h1>\r\n          <p itemprop=\"description\">Fantastic and fun for all your cheesy occasions.</p>\r\n          <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>\r\n          <p>Phone: <span itemprop=\"telephone\" content=\"+155501003333\">555-0100-3333</span></p>\r\n          <p>View <a itemprop=\"menu\" href=\"http://example.com/menu\">our menu</a>.</p>\r\n        </div>\r\n    </div>\r\n\r\n### A MusicGroup described in page alongside related entities (e.g. JSON-LD)\r\n\r\n* 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)\r\n* It records many other facts about her, using several different schema.org types.\r\n* 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. \r\n* 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](https://any23.apache.org/)) and all RDF tooling, which abstract away from concrete syntax.\r\n* 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.\r\n\r\n## Questions\r\n\r\n* Is mainEntity inverseOf the url property? Maybe...\r\n* Is this the same as foaf:primaryTopic? Yes.\r\n* 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...\r\n* Will this help close the gap between schema.org and Open Graph Protocol (OGP)? Potentially, yes. \r\n\r\n## Alternatives that do not work (for the purposes above)\r\n\r\n* 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 #215\r\n* 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](https://lists.w3.org/Archives/Public/public-vocabs/2014May/0273.html) )\r\n* Having mainEntity be a boolean property. Although it might be simpler to write mainEntity='true' or <link href=\"http://schema.org/True\" itemprop=\"mainEntity\"/>, the information we are recording is intrinsically related to the page carrying it.\r\n"},"comment":{"url":"https://api.github.com/repos/schemaorg/schemaorg/issues/comments/97540153","html_url":"https://github.com/schemaorg/schemaorg/issues/301#issuecomment-97540153","issue_url":"https://api.github.com/repos/schemaorg/schemaorg/issues/301","id":97540153,"user":{"login":"danbri","id":170265,"avatar_url":"https://avatars.githubusercontent.com/u/170265?v=3","gravatar_id":"","url":"https://api.github.com/users/danbri","html_url":"https://github.com/danbri","followers_url":"https://api.github.com/users/danbri/followers","following_url":"https://api.github.com/users/danbri/following{/other_user}","gists_url":"https://api.github.com/users/danbri/gists{/gist_id}","starred_url":"https://api.github.com/users/danbri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/danbri/subscriptions","organizations_url":"https://api.github.com/users/danbri/orgs","repos_url":"https://api.github.com/users/danbri/repos","events_url":"https://api.github.com/users/danbri/events{/privacy}","received_events_url":"https://api.github.com/users/danbri/received_events","type":"User","site_admin":false},"created_at":"2015-04-29T18:56:52Z","updated_at":"2015-04-29T18:56:52Z","body":"@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."}}