{"action":"created","comment":{"url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/comments/37203612","id":37203612,"diff_hunk":"@@ -0,0 +1,257 @@\n+#Contract Entities\r\n+####AuditableEntity\r\n+#####What is it?\r\n+`AuditableEntity` is the abstract base type for all OpenHDS entities. The class provides fields useful for ‘auditing’ or keeping track of meta information pertaining to the concrete type like when it was created and last modified.\r\n+######Required Fields:\r\n++ String uuid \r\n++ User insertBy \r\n++ Date insertDate \r\n++ User lastModifiedBy \r\n++ Date lastModifiedDate \r\n+\r\n+___\r\n+####AuditableCollectedEntity\r\n+(child of `AuditableEntity`)\r\n+#####What is it?\r\n+`AuditableCollectedEntity` is the abstract base type for all OpenHDS entities that are collected by a `FieldWorker`.\r\n+######Dependencies\r\n++ FieldWorker\r\n+\r\n+######Required Fields:\r\n++ FieldWorker collectedBy \r\n++ Date collectionDateTime\r\n+\r\n+___\r\n+####AuditableExtIdEntity\r\n+(child of `AuditableCollectedEntity`) \r\n+#####What is it?\r\n+`AuditableExtIdEntity` is an entity that is identifiable by an id external to the OpenHDS, i.e. the functionality of the OpenHDS is not dependent on it. \r\n+######Required Fields:\r\n++ String extId \r\n+\r\n+#Census Entities\r\n+####LocationHierarchy\r\n+(child of `AuditableExtIdEntity`)\r\n+#####What is it?\r\n+`LocationHierarchy` is a node in the tree that represents the study area. For example, at the top of a tree would be the The United States and it would have a child node for each of the 50 states. Each state node could have a child node for its cities and each city could have a child node for its districts and so on. `LocationHierarchy` extends `AuditableExtIdEntity` meaning it is identified by uuid as well as extId. \r\n+#####Dependencies\r\n++ FieldWorker\r\n++ LocationHierarchy\r\n++ LocationHierarchyLevel\r\n+\r\n+######Required Fields:\r\n++ String name\r\n++ String extId\r\n++ LocationHierarchy parent\r\n++ LocationHierarchyLevel level\r\n+\r\n+___\r\n+####LocationHierarchyLevel\r\n+(child of `AuditableEntity`)\r\n+#####What is it?\r\n+The levels of the `LocationHierarchy` tree are defined separately as `LocationHierarchyLevel`s and referenced by each instance of `LocationHierarchy`. From the previous example, the list of `LocationHierarchyLevel`s would be Country, State, City, District.\r\n+######Required Fields:\r\n++ int keyIdentifier\r\n++ String name\r\n+\r\n+___\r\n+####Location\r\n+(child of `AuditableExtIdEntity`)\r\n+#####What is it?\r\n+`Location` is the leaf node on the `LocationHierarchy` tree, it is the smallest geographical unit within a study area. From the previous example for `LocationHierarchy`, each building within a district could be modeled with `Location`. `Individual`s are residents at `Locations`.\r","path":"src/main/resources/documentation/domain-model-overview.md","position":61,"original_position":61,"commit_id":"cf4782560a3ce8da978b5ac6c8e67ef468149ef7","original_commit_id":"cf4782560a3ce8da978b5ac6c8e67ef468149ef7","user":{"login":"benjamin-heasly","id":1950775,"avatar_url":"https://avatars.githubusercontent.com/u/1950775?v=3","gravatar_id":"","url":"https://api.github.com/users/benjamin-heasly","html_url":"https://github.com/benjamin-heasly","followers_url":"https://api.github.com/users/benjamin-heasly/followers","following_url":"https://api.github.com/users/benjamin-heasly/following{/other_user}","gists_url":"https://api.github.com/users/benjamin-heasly/gists{/gist_id}","starred_url":"https://api.github.com/users/benjamin-heasly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/benjamin-heasly/subscriptions","organizations_url":"https://api.github.com/users/benjamin-heasly/orgs","repos_url":"https://api.github.com/users/benjamin-heasly/repos","events_url":"https://api.github.com/users/benjamin-heasly/events{/privacy}","received_events_url":"https://api.github.com/users/benjamin-heasly/received_events","type":"User","site_admin":false},"body":"I think you could leave out the Individual from this description.\r\n\r\nOn the other hand, I agree that it makes sense to describe how the entities relate to each other and how they model the real world.  I think a picture would help.  And also maybe an overview or summary section that describes how the entities interact to describe the real world, based on a simple real-world scenario.","created_at":"2015-08-17T16:01:45Z","updated_at":"2015-08-17T16:01:45Z","html_url":"https://github.com/benjamin-heasly/openhds-rest/pull/130#discussion_r37203612","pull_request_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130","_links":{"self":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/comments/37203612"},"html":{"href":"https://github.com/benjamin-heasly/openhds-rest/pull/130#discussion_r37203612"},"pull_request":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130"}}},"pull_request":{"url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130","id":42543794,"html_url":"https://github.com/benjamin-heasly/openhds-rest/pull/130","diff_url":"https://github.com/benjamin-heasly/openhds-rest/pull/130.diff","patch_url":"https://github.com/benjamin-heasly/openhds-rest/pull/130.patch","issue_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/130","number":130,"state":"open","locked":false,"title":"Domain Documentation","user":{"login":"nathan-wolfe-lienhardt","id":6571116,"avatar_url":"https://avatars.githubusercontent.com/u/6571116?v=3","gravatar_id":"","url":"https://api.github.com/users/nathan-wolfe-lienhardt","html_url":"https://github.com/nathan-wolfe-lienhardt","followers_url":"https://api.github.com/users/nathan-wolfe-lienhardt/followers","following_url":"https://api.github.com/users/nathan-wolfe-lienhardt/following{/other_user}","gists_url":"https://api.github.com/users/nathan-wolfe-lienhardt/gists{/gist_id}","starred_url":"https://api.github.com/users/nathan-wolfe-lienhardt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nathan-wolfe-lienhardt/subscriptions","organizations_url":"https://api.github.com/users/nathan-wolfe-lienhardt/orgs","repos_url":"https://api.github.com/users/nathan-wolfe-lienhardt/repos","events_url":"https://api.github.com/users/nathan-wolfe-lienhardt/events{/privacy}","received_events_url":"https://api.github.com/users/nathan-wolfe-lienhardt/received_events","type":"User","site_admin":false},"body":"This is a PR for the rough draft of the documentation.\r\n\r\nIt is indeed rough and sparse.\r\n\r\nSome of the fields on the entities are in the documentation as required, but not actually that way in the code yet. This is because I was referencing this [paper](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.97.8391&rep=rep1&type=pdf).\r\n\r\nI plan on having a section for each entity that goes into more of the validation details rather than just 'required fields', and I think that will be one of the most valuable parts of the documentation. As I determine and add those details, I will do so in the code as well so that the validation and documentation can actually reflect one another. I haven't added them here yet because I just needed to get the 'boilerplate' writing done for each of the entities and come up with a format for each entity that made sense.\r\n\r\nFurthermore, I think the field-specific descriptions make sense in the @Description annotation we have been using as it seems like that information is most pertinent when someone is actually coding. \r\n\r\nLet me know if you think there is some other section for each entity that should be added.\r\n","created_at":"2015-08-16T21:30:43Z","updated_at":"2015-08-17T16:01:45Z","closed_at":null,"merged_at":null,"merge_commit_sha":"acca83eff7535454e88962d083bd086ee385561c","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130/commits","review_comments_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130/comments","review_comment_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/comments{/number}","comments_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/130/comments","statuses_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/statuses/cf4782560a3ce8da978b5ac6c8e67ef468149ef7","head":{"label":"benjamin-heasly:domain-documentation","ref":"domain-documentation","sha":"cf4782560a3ce8da978b5ac6c8e67ef468149ef7","user":{"login":"benjamin-heasly","id":1950775,"avatar_url":"https://avatars.githubusercontent.com/u/1950775?v=3","gravatar_id":"","url":"https://api.github.com/users/benjamin-heasly","html_url":"https://github.com/benjamin-heasly","followers_url":"https://api.github.com/users/benjamin-heasly/followers","following_url":"https://api.github.com/users/benjamin-heasly/following{/other_user}","gists_url":"https://api.github.com/users/benjamin-heasly/gists{/gist_id}","starred_url":"https://api.github.com/users/benjamin-heasly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/benjamin-heasly/subscriptions","organizations_url":"https://api.github.com/users/benjamin-heasly/orgs","repos_url":"https://api.github.com/users/benjamin-heasly/repos","events_url":"https://api.github.com/users/benjamin-heasly/events{/privacy}","received_events_url":"https://api.github.com/users/benjamin-heasly/received_events","type":"User","site_admin":false},"repo":{"id":34867802,"name":"openhds-rest","full_name":"benjamin-heasly/openhds-rest","owner":{"login":"benjamin-heasly","id":1950775,"avatar_url":"https://avatars.githubusercontent.com/u/1950775?v=3","gravatar_id":"","url":"https://api.github.com/users/benjamin-heasly","html_url":"https://github.com/benjamin-heasly","followers_url":"https://api.github.com/users/benjamin-heasly/followers","following_url":"https://api.github.com/users/benjamin-heasly/following{/other_user}","gists_url":"https://api.github.com/users/benjamin-heasly/gists{/gist_id}","starred_url":"https://api.github.com/users/benjamin-heasly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/benjamin-heasly/subscriptions","organizations_url":"https://api.github.com/users/benjamin-heasly/orgs","repos_url":"https://api.github.com/users/benjamin-heasly/repos","events_url":"https://api.github.com/users/benjamin-heasly/events{/privacy}","received_events_url":"https://api.github.com/users/benjamin-heasly/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/benjamin-heasly/openhds-rest","description":"RESTful service for Health and Demographic Surveillance","fork":false,"url":"https://api.github.com/repos/benjamin-heasly/openhds-rest","forks_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/forks","keys_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/keys{/key_id}","collaborators_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/teams","hooks_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/hooks","issue_events_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/events{/number}","events_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/events","assignees_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/assignees{/user}","branches_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/branches{/branch}","tags_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/tags","blobs_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/refs{/sha}","trees_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/trees{/sha}","statuses_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/statuses/{sha}","languages_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/languages","stargazers_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/stargazers","contributors_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/contributors","subscribers_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/subscribers","subscription_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/subscription","commits_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/commits{/sha}","git_commits_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/commits{/sha}","comments_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/comments{/number}","issue_comment_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/comments{/number}","contents_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/contents/{+path}","compare_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/compare/{base}...{head}","merges_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/merges","archive_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/downloads","issues_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues{/number}","pulls_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls{/number}","milestones_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/milestones{/number}","notifications_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/labels{/name}","releases_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/releases{/id}","created_at":"2015-04-30T17:39:19Z","updated_at":"2015-06-15T17:53:35Z","pushed_at":"2015-08-16T21:30:43Z","git_url":"git://github.com/benjamin-heasly/openhds-rest.git","ssh_url":"git@github.com:benjamin-heasly/openhds-rest.git","clone_url":"https://github.com/benjamin-heasly/openhds-rest.git","svn_url":"https://github.com/benjamin-heasly/openhds-rest","homepage":null,"size":2473,"stargazers_count":2,"watchers_count":2,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":22,"forks":1,"open_issues":22,"watchers":2,"default_branch":"master"}},"base":{"label":"benjamin-heasly:master","ref":"master","sha":"17633c9a87449823115473b6c30bc9ed2ed25ebe","user":{"login":"benjamin-heasly","id":1950775,"avatar_url":"https://avatars.githubusercontent.com/u/1950775?v=3","gravatar_id":"","url":"https://api.github.com/users/benjamin-heasly","html_url":"https://github.com/benjamin-heasly","followers_url":"https://api.github.com/users/benjamin-heasly/followers","following_url":"https://api.github.com/users/benjamin-heasly/following{/other_user}","gists_url":"https://api.github.com/users/benjamin-heasly/gists{/gist_id}","starred_url":"https://api.github.com/users/benjamin-heasly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/benjamin-heasly/subscriptions","organizations_url":"https://api.github.com/users/benjamin-heasly/orgs","repos_url":"https://api.github.com/users/benjamin-heasly/repos","events_url":"https://api.github.com/users/benjamin-heasly/events{/privacy}","received_events_url":"https://api.github.com/users/benjamin-heasly/received_events","type":"User","site_admin":false},"repo":{"id":34867802,"name":"openhds-rest","full_name":"benjamin-heasly/openhds-rest","owner":{"login":"benjamin-heasly","id":1950775,"avatar_url":"https://avatars.githubusercontent.com/u/1950775?v=3","gravatar_id":"","url":"https://api.github.com/users/benjamin-heasly","html_url":"https://github.com/benjamin-heasly","followers_url":"https://api.github.com/users/benjamin-heasly/followers","following_url":"https://api.github.com/users/benjamin-heasly/following{/other_user}","gists_url":"https://api.github.com/users/benjamin-heasly/gists{/gist_id}","starred_url":"https://api.github.com/users/benjamin-heasly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/benjamin-heasly/subscriptions","organizations_url":"https://api.github.com/users/benjamin-heasly/orgs","repos_url":"https://api.github.com/users/benjamin-heasly/repos","events_url":"https://api.github.com/users/benjamin-heasly/events{/privacy}","received_events_url":"https://api.github.com/users/benjamin-heasly/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/benjamin-heasly/openhds-rest","description":"RESTful service for Health and Demographic Surveillance","fork":false,"url":"https://api.github.com/repos/benjamin-heasly/openhds-rest","forks_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/forks","keys_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/keys{/key_id}","collaborators_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/teams","hooks_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/hooks","issue_events_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/events{/number}","events_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/events","assignees_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/assignees{/user}","branches_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/branches{/branch}","tags_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/tags","blobs_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/refs{/sha}","trees_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/trees{/sha}","statuses_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/statuses/{sha}","languages_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/languages","stargazers_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/stargazers","contributors_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/contributors","subscribers_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/subscribers","subscription_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/subscription","commits_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/commits{/sha}","git_commits_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/git/commits{/sha}","comments_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/comments{/number}","issue_comment_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/comments{/number}","contents_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/contents/{+path}","compare_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/compare/{base}...{head}","merges_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/merges","archive_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/downloads","issues_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues{/number}","pulls_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls{/number}","milestones_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/milestones{/number}","notifications_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/labels{/name}","releases_url":"https://api.github.com/repos/benjamin-heasly/openhds-rest/releases{/id}","created_at":"2015-04-30T17:39:19Z","updated_at":"2015-06-15T17:53:35Z","pushed_at":"2015-08-16T21:30:43Z","git_url":"git://github.com/benjamin-heasly/openhds-rest.git","ssh_url":"git@github.com:benjamin-heasly/openhds-rest.git","clone_url":"https://github.com/benjamin-heasly/openhds-rest.git","svn_url":"https://github.com/benjamin-heasly/openhds-rest","homepage":null,"size":2473,"stargazers_count":2,"watchers_count":2,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":22,"forks":1,"open_issues":22,"watchers":2,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130"},"html":{"href":"https://github.com/benjamin-heasly/openhds-rest/pull/130"},"issue":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/130"},"comments":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/issues/130/comments"},"review_comments":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130/comments"},"review_comment":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/pulls/130/commits"},"statuses":{"href":"https://api.github.com/repos/benjamin-heasly/openhds-rest/statuses/cf4782560a3ce8da978b5ac6c8e67ef468149ef7"}}}}