GitHub PullRequestReviewCommentEvent at 2014-11-13 17:34:54
Repository: popit.poplus.org
Actor: tmtmtmtm
Payload: {"action":"created","comment":{"url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/comments/20307789","id":20307789,"diff_hunk":"@@ -0,0 +1,170 @@\n+---\n+layout: docs\n+title: Using the Popolo data model\n+---\n+\n+Popit uses the [Popolo specification](http://www.popoloproject.com/) to model people, organizations and their relationships. Understanding the best way to use this to model your needs is key to getting the best out of Popit. This page aims to explain to you the basic concepts of Popolo and how to use them in some common scenarios that come up when modeling parliaments.\n+\n+### Basic concepts ###\n+\n+Popolo, and hence Popit, data models are based on a few key objects:\n+\n+   * Persons\n+   * Organizations\n+   * Memberships\n+   * Posts\n+\n+#### Persons ####\n+\n+A Person in Popit, exactly as you'd imagine, stores data about a person.\n+\n+#### Organizations ####\n+\n+An organization is used to represent something to which people belong such as a parliament, political party or a company.\n+\n+#### Memberships ####\n+\n+A membership represents an association between two things. Mostly you'll use this to indicate that a person is a member of an organization.\n+\n+#### Posts ####\n+\n+A post is for the sort of position that it's useful to represent independent of the organization it's part of or the person who holds it. Unless you are modeling a parliament that has constituency seats ( e.g. Member of Parliament for Oxford East ) then you probably won't need posts.\n+\n+### But what about roles? ###\n+\n+It's possible for a membership, or a post, to have a role. A role is used to indicate something about the nature of the membership. E.g. for people in a party you could set the role of the membership to be member. Or for people on a partly list the role could be candidate.\n+\n+### How to use them together ###\n+\n+As we envisage that Popit will mostly be used to model people in parliaments we're going to provide a set of examples of how to model common parliamentary types.\n+\n+#### Party lists, no areas ####\n+\n+We're going to start with the simple example of a parliament where the members are selected proportionally from party lists. In this case you would have an organization for the Parliament, and one for each party. You would then add each person who was a member of parliament and create a membership for parliament and one for their party.\n+\n+For a typical member of parliament this would look something like:\n+\n+{% highlight json %}\n+{\n+    \"id\": \"org.mysociety.za/person/104\",\n+    \"family_name\": \"Sisulu\",\n+    \"given_names\": \"Max Vuyisile\",\n+    \"name\": \"Max Vuyisile Sisulu\",\n+    \"memberships\": [\n+      {\n+        \"url\": \"http://za-peoples-assembly.popit.mysociety.org/api/v0.1/memberships/org.mysociety.za/membership/104\",\n+        \"contact_details\": [],\n+        \"links\": [],\n+        \"person_id\": \"org.mysociety.za/person/104\",\n+        \"organization_id\": \"org.mysociety.za/party/anc\",\n+        \"id\": \"org.mysociety.za/membership/104\"\n+      },\n+      {\n+        \"url\": \"http://za-peoples-assembly.popit.mysociety.org/api/v0.1/memberships/org.mysociety.za/membership/743\",\n+        \"id\": \"org.mysociety.za/membership/743\",\n+        \"organization_id\": \"org.mysociety.za/house/national-assembly\",\n+        \"role\": \"Member\",\n+        \"person_id\": \"org.mysociety.za/person/104\",\n+        \"label\": \"Member\",\n+        \"start_date\": \"2009-05-06\",\n+        \"links\": [],\n+        \"contact_details\": []\n+      }\n+    ]\n+  }\n+}\n+{% endhighlight %}\n+\n+#### Party lists for geographic areas ####\n+\n+In this case candidates are still elected proportionally from party lists but the lists are specified per area. E.g. There would be a set of party Lists for South West England and multiple people would be elected for this area. In this case the model is the same are previously with the addition that when creating the memberships you assign an area to the membership.\n+\n+In this case the membership for the parliament would look something like this:\n+\n+{% highlight json %}\n+{\n+  \"url\": \"http://za-peoples-assembly.popit.mysociety.org/api/v0.1/memberships/org.mysociety.za/membership/743\",\n+  \"id\": \"org.mysociety.za/membership/743\",\n+  \"organization_id\": \"org.mysociety.za/house/national-assembly\",\n+  \"role\": \"Member\",\n+  \"person_id\": \"org.mysociety.za/person/104\",\n+  \"label\": \"Member\",\n+  \"start_date\": \"2009-05-06\",\n+  \"area\": {\n+    \"name\": \"Area Name\"\n+  },\n+  \"links\": [],\n+  \"contact_details\": []\n+}\n+{% endhighlight %}\n+\n+#### Constituency based parliament ####\n+\n+In this model there are a number of constituencies in which one member is elected. In this case we create a post for each constituency in the parliament. The elected representatives are then associated with the post using a membership.","path":"docs/using-the-popolo-data-model.md","position":103,"original_position":103,"commit_id":"fb204793b153d1d4e9c1de156896124f76216253","original_commit_id":"fb204793b153d1d4e9c1de156896124f76216253","user":{"login":"tmtmtmtm","id":57483,"avatar_url":"https://avatars.githubusercontent.com/u/57483?v=3","gravatar_id":"","url":"https://api.github.com/users/tmtmtmtm","html_url":"https://github.com/tmtmtmtm","followers_url":"https://api.github.com/users/tmtmtmtm/followers","following_url":"https://api.github.com/users/tmtmtmtm/following{/other_user}","gists_url":"https://api.github.com/users/tmtmtmtm/gists{/gist_id}","starred_url":"https://api.github.com/users/tmtmtmtm/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tmtmtmtm/subscriptions","organizations_url":"https://api.github.com/users/tmtmtmtm/orgs","repos_url":"https://api.github.com/users/tmtmtmtm/repos","events_url":"https://api.github.com/users/tmtmtmtm/events{/privacy}","received_events_url":"https://api.github.com/users/tmtmtmtm/received_events","type":"User","site_admin":false},"body":"Is this saying this is the only sensible way to do this; or there are multiple ways, but we think this is probably best; or just this is one good way to do it?","created_at":"2014-11-13T17:34:54Z","updated_at":"2014-11-13T17:34:54Z","html_url":"https://github.com/mysociety/popit.poplus.org/pull/33#discussion_r20307789","pull_request_url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33","_links":{"self":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/comments/20307789"},"html":{"href":"https://github.com/mysociety/popit.poplus.org/pull/33#discussion_r20307789"},"pull_request":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33"}}},"pull_request":{"url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33","id":24213204,"html_url":"https://github.com/mysociety/popit.poplus.org/pull/33","diff_url":"https://github.com/mysociety/popit.poplus.org/pull/33.diff","patch_url":"https://github.com/mysociety/popit.poplus.org/pull/33.patch","issue_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/33","number":33,"state":"open","locked":false,"title":"document popolo data model","user":{"login":"struan","id":5310,"avatar_url":"https://avatars.githubusercontent.com/u/5310?v=3","gravatar_id":"","url":"https://api.github.com/users/struan","html_url":"https://github.com/struan","followers_url":"https://api.github.com/users/struan/followers","following_url":"https://api.github.com/users/struan/following{/other_user}","gists_url":"https://api.github.com/users/struan/gists{/gist_id}","starred_url":"https://api.github.com/users/struan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/struan/subscriptions","organizations_url":"https://api.github.com/users/struan/orgs","repos_url":"https://api.github.com/users/struan/repos","events_url":"https://api.github.com/users/struan/events{/privacy}","received_events_url":"https://api.github.com/users/struan/received_events","type":"User","site_admin":false},"body":"Pages to document how to use the data model by using some common examples.\r\n\r\nAlso a tutorial on using the API and a page listing some of the client libraries available.","created_at":"2014-11-11T11:27:21Z","updated_at":"2014-11-13T17:34:54Z","closed_at":null,"merged_at":null,"merge_commit_sha":"feac0c3d3f8927340052884ae5560be18216a999","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33/commits","review_comments_url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33/comments","review_comment_url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/comments/{number}","comments_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/33/comments","statuses_url":"https://api.github.com/repos/mysociety/popit.poplus.org/statuses/fb204793b153d1d4e9c1de156896124f76216253","head":{"label":"mysociety:652-document-popolo-data-model","ref":"652-document-popolo-data-model","sha":"fb204793b153d1d4e9c1de156896124f76216253","user":{"login":"mysociety","id":141338,"avatar_url":"https://avatars.githubusercontent.com/u/141338?v=3","gravatar_id":"","url":"https://api.github.com/users/mysociety","html_url":"https://github.com/mysociety","followers_url":"https://api.github.com/users/mysociety/followers","following_url":"https://api.github.com/users/mysociety/following{/other_user}","gists_url":"https://api.github.com/users/mysociety/gists{/gist_id}","starred_url":"https://api.github.com/users/mysociety/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mysociety/subscriptions","organizations_url":"https://api.github.com/users/mysociety/orgs","repos_url":"https://api.github.com/users/mysociety/repos","events_url":"https://api.github.com/users/mysociety/events{/privacy}","received_events_url":"https://api.github.com/users/mysociety/received_events","type":"Organization","site_admin":false},"repo":{"id":18882077,"name":"popit.poplus.org","full_name":"mysociety/popit.poplus.org","owner":{"login":"mysociety","id":141338,"avatar_url":"https://avatars.githubusercontent.com/u/141338?v=3","gravatar_id":"","url":"https://api.github.com/users/mysociety","html_url":"https://github.com/mysociety","followers_url":"https://api.github.com/users/mysociety/followers","following_url":"https://api.github.com/users/mysociety/following{/other_user}","gists_url":"https://api.github.com/users/mysociety/gists{/gist_id}","starred_url":"https://api.github.com/users/mysociety/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mysociety/subscriptions","organizations_url":"https://api.github.com/users/mysociety/orgs","repos_url":"https://api.github.com/users/mysociety/repos","events_url":"https://api.github.com/users/mysociety/events{/privacy}","received_events_url":"https://api.github.com/users/mysociety/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/mysociety/popit.poplus.org","description":"PopIt Poplus homepage","fork":false,"url":"https://api.github.com/repos/mysociety/popit.poplus.org","forks_url":"https://api.github.com/repos/mysociety/popit.poplus.org/forks","keys_url":"https://api.github.com/repos/mysociety/popit.poplus.org/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mysociety/popit.poplus.org/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mysociety/popit.poplus.org/teams","hooks_url":"https://api.github.com/repos/mysociety/popit.poplus.org/hooks","issue_events_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/events{/number}","events_url":"https://api.github.com/repos/mysociety/popit.poplus.org/events","assignees_url":"https://api.github.com/repos/mysociety/popit.poplus.org/assignees{/user}","branches_url":"https://api.github.com/repos/mysociety/popit.poplus.org/branches{/branch}","tags_url":"https://api.github.com/repos/mysociety/popit.poplus.org/tags","blobs_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/refs{/sha}","trees_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mysociety/popit.poplus.org/statuses/{sha}","languages_url":"https://api.github.com/repos/mysociety/popit.poplus.org/languages","stargazers_url":"https://api.github.com/repos/mysociety/popit.poplus.org/stargazers","contributors_url":"https://api.github.com/repos/mysociety/popit.poplus.org/contributors","subscribers_url":"https://api.github.com/repos/mysociety/popit.poplus.org/subscribers","subscription_url":"https://api.github.com/repos/mysociety/popit.poplus.org/subscription","commits_url":"https://api.github.com/repos/mysociety/popit.poplus.org/commits{/sha}","git_commits_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/commits{/sha}","comments_url":"https://api.github.com/repos/mysociety/popit.poplus.org/comments{/number}","issue_comment_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/comments/{number}","contents_url":"https://api.github.com/repos/mysociety/popit.poplus.org/contents/{+path}","compare_url":"https://api.github.com/repos/mysociety/popit.poplus.org/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mysociety/popit.poplus.org/merges","archive_url":"https://api.github.com/repos/mysociety/popit.poplus.org/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mysociety/popit.poplus.org/downloads","issues_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues{/number}","pulls_url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls{/number}","milestones_url":"https://api.github.com/repos/mysociety/popit.poplus.org/milestones{/number}","notifications_url":"https://api.github.com/repos/mysociety/popit.poplus.org/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mysociety/popit.poplus.org/labels{/name}","releases_url":"https://api.github.com/repos/mysociety/popit.poplus.org/releases{/id}","created_at":"2014-04-17T14:52:48Z","updated_at":"2014-09-17T14:37:50Z","pushed_at":"2014-11-06T17:21:56Z","git_url":"git://github.com/mysociety/popit.poplus.org.git","ssh_url":"git@github.com:mysociety/popit.poplus.org.git","clone_url":"https://github.com/mysociety/popit.poplus.org.git","svn_url":"https://github.com/mysociety/popit.poplus.org","homepage":"http://popit.poplus.org","size":1412,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":1,"mirror_url":null,"open_issues_count":6,"forks":1,"open_issues":6,"watchers":0,"default_branch":"gh-pages"}},"base":{"label":"mysociety:gh-pages","ref":"gh-pages","sha":"f0fecf02a9bf5ca6b54623e41a1670b1cf4e1fdf","user":{"login":"mysociety","id":141338,"avatar_url":"https://avatars.githubusercontent.com/u/141338?v=3","gravatar_id":"","url":"https://api.github.com/users/mysociety","html_url":"https://github.com/mysociety","followers_url":"https://api.github.com/users/mysociety/followers","following_url":"https://api.github.com/users/mysociety/following{/other_user}","gists_url":"https://api.github.com/users/mysociety/gists{/gist_id}","starred_url":"https://api.github.com/users/mysociety/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mysociety/subscriptions","organizations_url":"https://api.github.com/users/mysociety/orgs","repos_url":"https://api.github.com/users/mysociety/repos","events_url":"https://api.github.com/users/mysociety/events{/privacy}","received_events_url":"https://api.github.com/users/mysociety/received_events","type":"Organization","site_admin":false},"repo":{"id":18882077,"name":"popit.poplus.org","full_name":"mysociety/popit.poplus.org","owner":{"login":"mysociety","id":141338,"avatar_url":"https://avatars.githubusercontent.com/u/141338?v=3","gravatar_id":"","url":"https://api.github.com/users/mysociety","html_url":"https://github.com/mysociety","followers_url":"https://api.github.com/users/mysociety/followers","following_url":"https://api.github.com/users/mysociety/following{/other_user}","gists_url":"https://api.github.com/users/mysociety/gists{/gist_id}","starred_url":"https://api.github.com/users/mysociety/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mysociety/subscriptions","organizations_url":"https://api.github.com/users/mysociety/orgs","repos_url":"https://api.github.com/users/mysociety/repos","events_url":"https://api.github.com/users/mysociety/events{/privacy}","received_events_url":"https://api.github.com/users/mysociety/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/mysociety/popit.poplus.org","description":"PopIt Poplus homepage","fork":false,"url":"https://api.github.com/repos/mysociety/popit.poplus.org","forks_url":"https://api.github.com/repos/mysociety/popit.poplus.org/forks","keys_url":"https://api.github.com/repos/mysociety/popit.poplus.org/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mysociety/popit.poplus.org/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mysociety/popit.poplus.org/teams","hooks_url":"https://api.github.com/repos/mysociety/popit.poplus.org/hooks","issue_events_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/events{/number}","events_url":"https://api.github.com/repos/mysociety/popit.poplus.org/events","assignees_url":"https://api.github.com/repos/mysociety/popit.poplus.org/assignees{/user}","branches_url":"https://api.github.com/repos/mysociety/popit.poplus.org/branches{/branch}","tags_url":"https://api.github.com/repos/mysociety/popit.poplus.org/tags","blobs_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/refs{/sha}","trees_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mysociety/popit.poplus.org/statuses/{sha}","languages_url":"https://api.github.com/repos/mysociety/popit.poplus.org/languages","stargazers_url":"https://api.github.com/repos/mysociety/popit.poplus.org/stargazers","contributors_url":"https://api.github.com/repos/mysociety/popit.poplus.org/contributors","subscribers_url":"https://api.github.com/repos/mysociety/popit.poplus.org/subscribers","subscription_url":"https://api.github.com/repos/mysociety/popit.poplus.org/subscription","commits_url":"https://api.github.com/repos/mysociety/popit.poplus.org/commits{/sha}","git_commits_url":"https://api.github.com/repos/mysociety/popit.poplus.org/git/commits{/sha}","comments_url":"https://api.github.com/repos/mysociety/popit.poplus.org/comments{/number}","issue_comment_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/comments/{number}","contents_url":"https://api.github.com/repos/mysociety/popit.poplus.org/contents/{+path}","compare_url":"https://api.github.com/repos/mysociety/popit.poplus.org/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mysociety/popit.poplus.org/merges","archive_url":"https://api.github.com/repos/mysociety/popit.poplus.org/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mysociety/popit.poplus.org/downloads","issues_url":"https://api.github.com/repos/mysociety/popit.poplus.org/issues{/number}","pulls_url":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls{/number}","milestones_url":"https://api.github.com/repos/mysociety/popit.poplus.org/milestones{/number}","notifications_url":"https://api.github.com/repos/mysociety/popit.poplus.org/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mysociety/popit.poplus.org/labels{/name}","releases_url":"https://api.github.com/repos/mysociety/popit.poplus.org/releases{/id}","created_at":"2014-04-17T14:52:48Z","updated_at":"2014-09-17T14:37:50Z","pushed_at":"2014-11-06T17:21:56Z","git_url":"git://github.com/mysociety/popit.poplus.org.git","ssh_url":"git@github.com:mysociety/popit.poplus.org.git","clone_url":"https://github.com/mysociety/popit.poplus.org.git","svn_url":"https://github.com/mysociety/popit.poplus.org","homepage":"http://popit.poplus.org","size":1412,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":1,"mirror_url":null,"open_issues_count":6,"forks":1,"open_issues":6,"watchers":0,"default_branch":"gh-pages"}},"_links":{"self":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33"},"html":{"href":"https://github.com/mysociety/popit.poplus.org/pull/33"},"issue":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/33"},"comments":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/issues/33/comments"},"review_comments":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33/comments"},"review_comment":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/pulls/33/commits"},"statuses":{"href":"https://api.github.com/repos/mysociety/popit.poplus.org/statuses/fb204793b153d1d4e9c1de156896124f76216253"}}}}