From 788e873eec879ce8b437951a981c379648d96d15 Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Sun, 11 Jun 2017 09:04:18 -0500 Subject: [PATCH 1/7] Starting reconcilliation pep with some rought notes --- proposals/drafts/reconciliation.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 proposals/drafts/reconciliation.md diff --git a/proposals/drafts/reconciliation.md b/proposals/drafts/reconciliation.md new file mode 100644 index 0000000..7409eff --- /dev/null +++ b/proposals/drafts/reconciliation.md @@ -0,0 +1,28 @@ +# Reconcilliation service: + +## Prior Art + +- https://web.archive.org/web/20161108220043/https://www.newschallenge.org/challenge/elections/entries/politician-reconciliation-service +- https://web.archive.org/web/20130609195642/https://www.newschallenge.org/open/open-government/submission/civic-data-standardization-bootstrapper/ +- https://github.com/newsdev/nyt-entity-service +- https://github.com/pudo/nomenklatura +- google refine reconcilliation and freebase + + +## Notes + +- match endpoint +- add endpoint +- bulk add endpoint +- bulk access to data +- copyright assignment to whom (shouldn't be datamade) + + +## Key questions: +1. What's the governance for accepting new entities +2. What's the governance for merging and splitting existing entities +3. If there is a merge or split how will changed entity ids propogate +4. While DataMade can commit to supporting the service we are not going to make our full stack of dedupe.io open source +is this a problem +5. What type of entities are in scope--probably start with people. + From 370eae1c9b6a0019477422c07a4e22ddf4680965 Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Wed, 14 Jun 2017 16:52:10 -0500 Subject: [PATCH 2/7] stubbing out the main sections of the reconcilliation --- proposals/drafts/reconciliation.md | 28 ------ proposals/drafts/reconciliation.rst | 142 ++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 28 deletions(-) delete mode 100644 proposals/drafts/reconciliation.md create mode 100644 proposals/drafts/reconciliation.rst diff --git a/proposals/drafts/reconciliation.md b/proposals/drafts/reconciliation.md deleted file mode 100644 index 7409eff..0000000 --- a/proposals/drafts/reconciliation.md +++ /dev/null @@ -1,28 +0,0 @@ -# Reconcilliation service: - -## Prior Art - -- https://web.archive.org/web/20161108220043/https://www.newschallenge.org/challenge/elections/entries/politician-reconciliation-service -- https://web.archive.org/web/20130609195642/https://www.newschallenge.org/open/open-government/submission/civic-data-standardization-bootstrapper/ -- https://github.com/newsdev/nyt-entity-service -- https://github.com/pudo/nomenklatura -- google refine reconcilliation and freebase - - -## Notes - -- match endpoint -- add endpoint -- bulk add endpoint -- bulk access to data -- copyright assignment to whom (shouldn't be datamade) - - -## Key questions: -1. What's the governance for accepting new entities -2. What's the governance for merging and splitting existing entities -3. If there is a merge or split how will changed entity ids propogate -4. While DataMade can commit to supporting the service we are not going to make our full stack of dedupe.io open source -is this a problem -5. What type of entities are in scope--probably start with people. - diff --git a/proposals/drafts/reconciliation.rst b/proposals/drafts/reconciliation.rst new file mode 100644 index 0000000..fd1aaf6 --- /dev/null +++ b/proposals/drafts/reconciliation.rst @@ -0,0 +1,142 @@ +============================= +OCDEP: Reconciliation Service +============================= + +:Created: 2016-12-28 +:Author: Forest Gregg, `DataMade `_ +:Status: Proposed + +Overview +======== + +Technical specification for a entity reconciliation service for Open +Civic Data identifiers and governance for managing those identifiers. + + +Rationale +========= + +Different publishers of civic data often release data about the same +people or organizations. However, the data almost never use the same +identifiers. An end user who wants to use multiple data sources--say +researching the relation between campaign finances and electoral +success--has to do all the work of figuring out which records are +about the same people and organizations. + +This record linkage task acts as major obstacle between the civic data +and the ultimate task that data users want to accomplish. + +A reconciliation service would allow data publishers to coordinate, in +a loosely coupled way, to use the same identifiers to refer the same +people and organizations--removing this barrier for our data users. + + +Implementation +============== + +Scope +----- + +Let's start with politicians. Let's define a politician as someone who +has ever run elected office. (We need a tighter definition of "run for elected office") + +API +--- + +match +_____ + +match endpoint can takes 1 or more match fields and returns possible matches with identifiers + +GET + +id +___ + +for a specific id return all the information we associated + +if the id has been subsumed, 302 to the correct place + +GET + +mint +____ + +Submit minimum data fields for new entity return new id + +maybe require a token from match? + + +merge +_____ +submit identifiers, returns new identifier + +POST + + +split +_____ + +submit arrays of reference identfiers from within a id and split into new ids, return new ids + +POST + +Governance +__________ + +mint, merge, and split are powerful claims that can will affect other users. + +proposed permission model + +unprivileged + +- match methods +- id methods + +publisher + +- mint method +- merge method +- split method + +publishers will get notifications if the entities they uploaded are changed by another publisher, and can take action? + + +Bulk access +----------- + +The underlying data for the service will be available as a daily backup + +Backend +------- +The reconcilliation engine supporting this API will be unspecified. + + +Copyright of OCD identifiers +---------------------------- + +They will be dedicated to the public domain + +Publisshers will need to agree that they will not upload data that is under copyright. + + + + + + + + + + +- https://web.archive.org/web/20161108220043/https://www.newschallenge.org/challenge/elections/entries/politician-reconciliation-service +- https://web.archive.org/web/20130609195642/https://www.newschallenge.org/open/open-government/submission/civic-data-standardization-bootstrapper/ +- https://github.com/newsdev/nyt-entity-service +- https://github.com/pudo/nomenklatura +- google refine reconcilliation and freebase + + +Copyright +========= +This document has been placed in the public domain per the Creative Commons CC0 1.0 Universal license (http://creativecommons.org/publicdomain/zero/1.0/deed). + + From b99cae63c7ab3ba7a951aeed0256a2cb2e845e4e Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Sun, 23 Jul 2017 22:47:35 -0500 Subject: [PATCH 3/7] fleshing out endpoints and describing scope --- proposals/drafts/reconciliation.rst | 123 +++++++++++++++++++--------- 1 file changed, 85 insertions(+), 38 deletions(-) diff --git a/proposals/drafts/reconciliation.rst b/proposals/drafts/reconciliation.rst index fd1aaf6..40f591b 100644 --- a/proposals/drafts/reconciliation.rst +++ b/proposals/drafts/reconciliation.rst @@ -16,19 +16,18 @@ Civic Data identifiers and governance for managing those identifiers. Rationale ========= -Different publishers of civic data often release data about the same -people or organizations. However, the data almost never use the same -identifiers. An end user who wants to use multiple data sources--say -researching the relation between campaign finances and electoral -success--has to do all the work of figuring out which records are -about the same people and organizations. +Publishers of civic data often release data about the same set of +people and organizations. Different sources almost never use the same +identifiers, leaving it to end users to attempt to combine data. -This record linkage task acts as major obstacle between the civic data -and the ultimate task that data users want to accomplish. +This record linkage task is difficult and, at scale, is beyond the +ability and resources available to most data users. This obstacle +prevents many of the uses that civic data publishers would like their +data to enable. A reconciliation service would allow data publishers to coordinate, in a loosely coupled way, to use the same identifiers to refer the same -people and organizations--removing this barrier for our data users. +people and organizations--removing obstacle for data users. Implementation @@ -37,49 +36,99 @@ Implementation Scope ----- -Let's start with politicians. Let's define a politician as someone who -has ever run elected office. (We need a tighter definition of "run for elected office") +This current proposal is limited to a service to support common +identifiers for politicians. In the future it may be extended to other +types of civic entities. + +For our purposes, a politician is person who has formed a political +committee to pursue elected office. This definition should be adequate +for the current target set of publishers those who publish data on +campaign finance, electioneering, election results, and legislative +actions. Individual campaign donors, lobbyists, civil servants, +campaign operatives are currently not in scope. + + +Reconciliation Service +---------------------- + +The reconciliation service will be a web service that data publishers +will largely interact with through a REST API. + +While, the internal implementation details of the service are outside +of the scope of this proposal, this proposal will discuss data access +provisions necessary to allow for continuity if the service provider +is unable or unwilling to maintain the service. + API --- -match -_____ +.. http:get:: /search -match endpoint can takes 1 or more match fields and returns possible matches with identifiers + Attempts to find the ocd identifier for a politician -GET + :query name: a name of the politician + :query jurisdiction_id: an OCD id for the jurisdiction of the organization that the politician is seeking election into or is a member of + :query office: (optional) a name of the office + :query birth_date: (optional) the birth date of the politician + :query active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office + :status 200 OK: no error, returns a list of possible ids with match scores + :status 404 Not Found: could not find any possible matches -id -___ +.. http:get:: /identifier/(str:ocd_identifier) -for a specific id return all the information we associated + Shows all existing records and linkage history for a politician -if the id has been subsumed, 302 to the correct place + :param ocd_identifier: politician's OCD identifier + :type ocd_identifier: str + :status 200 OK: no error + :status 404 Not Found: no politician with that identifier found + :status 301 Moved Permanently: if an ocd_identifier has been merged into another identifier, redirect to :http:get:`/identifier/(str:new_ocd_identifier)` -GET +.. http:post:: /identifier -mint -____ + Mint new ocd identifier -Submit minimum data fields for new entity return new id + :form name: a name of the politician + :form jurisdiction_id: an OCD id for the jurisdiction of the organization that the politician is seeking election into or is a member of + :form office: (optional) a name of the office + :form birth_date: (optional) the birth date of the politician + :form active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office + :reqheader Authorization: OAuth token to authenticate + :status 201 Created: returns ocd_identifier -maybe require a token from match? - +.. http:put:: /identifier/(str:ocd_identifier) -merge -_____ -submit identifiers, returns new identifier + Add data about politician -POST + :param ocd_identifier: politician's OCD identifier + :type ocd_identifier: str + :form name: a name of the politician + :form jurisdiction_id: an OCD id for the jurisdiction of the organization that the politician is seeking election into or is a member of + :form office: (optional) a name of the office + :form birth_date: (optional) the birth date of the politician + :form active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office + :reqheader Authorization: OAuth token to authenticate + :status 201 Created: return existing records and linkage history for a politician +.. http:post:: /merge -split -_____ + Merges identifiers -submit arrays of reference identfiers from within a id and split into new ids, return new ids + :form ids: array of ids to merge + :reqheader Authorization: OAuth token to authenticate + :status 201 Created: returns surviving ocd_identifier + +.. http:post:: /split/(str:ocd_identifier) -POST + Split identifiers + + :param ocd_identifier: politician's OCD identifier + :type ocd_identifier: str + :form ids: array of reference ids to remove and turn into new id + :reqheader Authorization: OAuth token to authenticate + :status 201 Created: returns ocd_identifier for the split data + Governance __________ @@ -99,7 +148,8 @@ publisher - merge method - split method -publishers will get notifications if the entities they uploaded are changed by another publisher, and can take action? +publishers will get notifications if the entities they uploaded are +changed by another publisher, and can take action. Bulk access @@ -107,9 +157,6 @@ Bulk access The underlying data for the service will be available as a daily backup -Backend -------- -The reconcilliation engine supporting this API will be unspecified. Copyright of OCD identifiers @@ -127,7 +174,7 @@ Publisshers will need to agree that they will not upload data that is under copy - +- http://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.2001414 - https://web.archive.org/web/20161108220043/https://www.newschallenge.org/challenge/elections/entries/politician-reconciliation-service - https://web.archive.org/web/20130609195642/https://www.newschallenge.org/open/open-government/submission/civic-data-standardization-bootstrapper/ - https://github.com/newsdev/nyt-entity-service From 2d041f96f0477d3230976eb7c60c47ea8e4e9180 Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Mon, 24 Jul 2017 19:10:26 -0500 Subject: [PATCH 4/7] multiple choice for split case add delete method --- proposals/drafts/reconciliation.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/proposals/drafts/reconciliation.rst b/proposals/drafts/reconciliation.rst index 40f591b..15483a3 100644 --- a/proposals/drafts/reconciliation.rst +++ b/proposals/drafts/reconciliation.rst @@ -84,6 +84,7 @@ API :status 200 OK: no error :status 404 Not Found: no politician with that identifier found :status 301 Moved Permanently: if an ocd_identifier has been merged into another identifier, redirect to :http:get:`/identifier/(str:new_ocd_identifier)` + :status 300 Multiple Choices: this id has split, return options .. http:post:: /identifier @@ -109,7 +110,11 @@ API :form birth_date: (optional) the birth date of the politician :form active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office :reqheader Authorization: OAuth token to authenticate - :status 201 Created: return existing records and linkage history for a politician + :status 201 Created: return record id + +.. http::delete:: /identifier/(str:ocd_identifier) + + Delete the record from politician id .. http:post:: /merge @@ -121,13 +126,15 @@ API .. http:post:: /split/(str:ocd_identifier) - Split identifiers + Split identifiers. This will create new ids for both sides of the split. + The old id will return a 300 :param ocd_identifier: politician's OCD identifier :type ocd_identifier: str :form ids: array of reference ids to remove and turn into new id :reqheader Authorization: OAuth token to authenticate - :status 201 Created: returns ocd_identifier for the split data + :status 201 Created: returns new ocd_identifiers for both sides of the split + Governance @@ -164,7 +171,8 @@ Copyright of OCD identifiers They will be dedicated to the public domain -Publisshers will need to agree that they will not upload data that is under copyright. +Publisshers will need to agree that they will not upload data that is +under copyright, and agree to dedicate all data to the public domain. From 9342c93e0770f84654e97b0521880cc40f9fde6a Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Fri, 8 Sep 2017 17:09:37 -0500 Subject: [PATCH 5/7] started to think about balancing gets and puts --- proposals/drafts/reconciliation.rst | 38 +++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/proposals/drafts/reconciliation.rst b/proposals/drafts/reconciliation.rst index 15483a3..d199fcf 100644 --- a/proposals/drafts/reconciliation.rst +++ b/proposals/drafts/reconciliation.rst @@ -69,11 +69,45 @@ API :query name: a name of the politician :query jurisdiction_id: an OCD id for the jurisdiction of the organization that the politician is seeking election into or is a member of - :query office: (optional) a name of the office + :query role: (optional) a name of the role associated with a post + :query active_date: (optional) a date, date range, year, year range + when the politician was seeking or held this + role + :query post_label: the label of the post :query birth_date: (optional) the birth date of the politician - :query active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office :status 200 OK: no error, returns a list of possible ids with match scores :status 404 Not Found: could not find any possible matches + :status 402 Payment required: If the balance between data added (puts and posts on `/identifier`) and searches is out of wack. This reduce + :status 429 Too Many Requests: Rate limiting + + :reqheader Authorization: optional OAuth token to authenticate + :resheader Balance: Balance between data added and data searched + + + **Example request**: + + .. sourcecode:: http + + GET /search?jurisdiction_id=ocd-jurisdiction/country:us/state:il/place:chicago/government&name="Ed Burke" HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/javascript + + [{"politician": {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Ed Burke", + "ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2" + "birth_date": null, + "posts": {"role": "Alderman", "label": "Ward 3"} + }, + "match_score": 0.74} + ] .. http:get:: /identifier/(str:ocd_identifier) From 7e36b5f09be1f1c606306a1b77b81d5ea239d799 Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Tue, 5 Dec 2017 16:05:49 -0600 Subject: [PATCH 6/7] flesh out methods --- proposals/drafts/reconciliation.rst | 197 +++++++++++++++++++++------- 1 file changed, 149 insertions(+), 48 deletions(-) diff --git a/proposals/drafts/reconciliation.rst b/proposals/drafts/reconciliation.rst index d199fcf..8a255d6 100644 --- a/proposals/drafts/reconciliation.rst +++ b/proposals/drafts/reconciliation.rst @@ -77,11 +77,10 @@ API :query birth_date: (optional) the birth date of the politician :status 200 OK: no error, returns a list of possible ids with match scores :status 404 Not Found: could not find any possible matches - :status 402 Payment required: If the balance between data added (puts and posts on `/identifier`) and searches is out of wack. This reduce :status 429 Too Many Requests: Rate limiting :reqheader Authorization: optional OAuth token to authenticate - :resheader Balance: Balance between data added and data searched + :resheader Balance: Balance between data added (search requests) and data searched (identifier post) **Example request**: @@ -98,14 +97,14 @@ API HTTP/1.1 200 OK Vary: Accept - Content-Type: text/javascript - - [{"politician": {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", - "name": "Ed Burke", - "ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2" - "birth_date": null, - "posts": {"role": "Alderman", "label": "Ward 3"} - }, + Content-Type: text/json + + [{"best reference": {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Ed Burke", + "birth_date": null, + "post": {"role": "Alderman", "label": "Ward 3"} + }, + "ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2", "match_score": 0.74} ] @@ -118,7 +117,29 @@ API :status 200 OK: no error :status 404 Not Found: no politician with that identifier found :status 301 Moved Permanently: if an ocd_identifier has been merged into another identifier, redirect to :http:get:`/identifier/(str:new_ocd_identifier)` - :status 300 Multiple Choices: this id has split, return options + :status 300 Multiple Choices: this id has split, return options + + **Example request**: + + .. sourcecode:: http + + GET /identifier/ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2 HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript + + **Example response**: + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + {"references": [{"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Ed Burke", + "birth_date": null, + "post": {"role": "Alderman", "label": "Ward 3"} + }], + "ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2"} + .. http:post:: /identifier @@ -126,11 +147,35 @@ API :form name: a name of the politician :form jurisdiction_id: an OCD id for the jurisdiction of the organization that the politician is seeking election into or is a member of - :form office: (optional) a name of the office + :form post: (optional) a name of the office :form birth_date: (optional) the birth date of the politician :form active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office :reqheader Authorization: OAuth token to authenticate :status 201 Created: returns ocd_identifier + :status 412 Precondition Failed: required information is missing or malformed + :status 401 Unauthorized: missing or invalid authorization token + + **Example Request**: + + .. sourcecode:: http + + POST /identifier HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript + Content-Type: application/json + Authorization: "Authorization: credentials" + + {"name": "Danny Solis", + "jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "post": {"role": "Alderman", "label": "Ward 14"}} + + **Example Response**: + + HTTP/1.1 201 OK + Vary: Accept + Content-Type: text/json + + {"ocd_id": "ocd-person/v12caddf-gdag-2faf-147d-bfas84e096e2"} .. http:put:: /identifier/(str:ocd_identifier) @@ -138,18 +183,52 @@ API :param ocd_identifier: politician's OCD identifier :type ocd_identifier: str - :form name: a name of the politician + :form name: (optional) a name of the politician :form jurisdiction_id: an OCD id for the jurisdiction of the organization that the politician is seeking election into or is a member of :form office: (optional) a name of the office :form birth_date: (optional) the birth date of the politician :form active_date: (optional) a date, date range, year, year range when the politician was seeking or held this office :reqheader Authorization: OAuth token to authenticate - :status 201 Created: return record id + :status 200 Created: return record + + **Example Request**: + + .. sourcecode:: http + + PUT /identifier/ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2 HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript + Content-Type: application/json + Authorization: "Authorization: credentials" + + {"name": "Edward Burke", + "ocd-jurisdiction/country:us/state:il/place:chicago/government"} + + **Example Response**: + + HTTP/1.1 201 OK + Vary: Accept + Content-Type: text/json + + {"references": {109234: {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Ed Burke", + "birth_date": null, + "post": {"role": "Alderman", "label": "Ward 3"} + }, + 109236: {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Edward Burke", + "birth_date": null, + "post": null + }}, + "ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2"} .. http::delete:: /identifier/(str:ocd_identifier) Delete the record from politician id + :reqheader Authorization: OAuth token to authenticate + :status 204 No Content: delete identifier + .. http:post:: /merge Merges identifiers @@ -157,6 +236,39 @@ API :form ids: array of ids to merge :reqheader Authorization: OAuth token to authenticate :status 201 Created: returns surviving ocd_identifier + + **Example Request**: + + .. sourcecode:: http + + POST /merge HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript + Content-Type: application/json + Authorization: "Authorization: credentials" + + ["ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2", "ocd-person/v12caddf-gdag-2faf-147d-bfas84e096e2"] + + **Example Response**: + + HTTP/1.1 201 OK + Vary: Accept + Content-Type: text/json + + {"references": {109234: {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Ed Burke", + "birth_date": null, + "post": {"role": "Alderman", "label": "Ward 3"} + }, + 109236: {"jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "name": "Edward Burke", + "birth_date": null, + "post": null + }, + 109235: {"name": "Danny Solis", + "jurisdiction_id": "ocd-jurisdiction/country:us/state:il/place:chicago/government", + "post": {"role": "Alderman", "label": "Ward 14"}}, + "ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2"} .. http:post:: /split/(str:ocd_identifier) @@ -167,30 +279,35 @@ API :type ocd_identifier: str :form ids: array of reference ids to remove and turn into new id :reqheader Authorization: OAuth token to authenticate - :status 201 Created: returns new ocd_identifiers for both sides of the split + :status 201 Created: returns new ocd_identifiers for the split - - -Governance -__________ - -mint, merge, and split are powerful claims that can will affect other users. + .. sourcecode:: http + + POST /split/ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2 HTTP/1.1 + Host: example.com + Accept: application/json, text/javascript + Content-Type: application/json + Authorization: "Authorization: credentials" -proposed permission model + [109235] -unprivileged + **Example Response**: + + HTTP/1.1 201 OK + Vary: Accept + Content-Type: text/json -- match methods -- id methods + {"ocd_id": "ocd-person/912c8ddf-8d04-4f7f-847d-2daf84e096e2"} + -publisher +Governance +__________ -- mint method -- merge method -- split method +`mint`, `merge`, and `split` are powerful claims that should be reserved +to trusted publishers. -publishers will get notifications if the entities they uploaded are -changed by another publisher, and can take action. +Publishers will get notifications if the entities they uploaded are +changed by another publisher. Bulk access @@ -199,31 +316,15 @@ Bulk access The underlying data for the service will be available as a daily backup - Copyright of OCD identifiers ---------------------------- They will be dedicated to the public domain -Publisshers will need to agree that they will not upload data that is +Publishers will need to agree that they will not upload data that is under copyright, and agree to dedicate all data to the public domain. - - - - - - - -- http://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.2001414 -- https://web.archive.org/web/20161108220043/https://www.newschallenge.org/challenge/elections/entries/politician-reconciliation-service -- https://web.archive.org/web/20130609195642/https://www.newschallenge.org/open/open-government/submission/civic-data-standardization-bootstrapper/ -- https://github.com/newsdev/nyt-entity-service -- https://github.com/pudo/nomenklatura -- google refine reconcilliation and freebase - - Copyright ========= This document has been placed in the public domain per the Creative Commons CC0 1.0 Universal license (http://creativecommons.org/publicdomain/zero/1.0/deed). From 98d470792630e5a9b3330b0812258b954e991d0a Mon Sep 17 00:00:00 2001 From: Forest Gregg Date: Tue, 5 Dec 2017 16:08:37 -0600 Subject: [PATCH 7/7] add http rest requirements --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index dfe44bb..0d2c6c1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,3 +5,4 @@ Sphinx==1.2.2 argparse==1.2.1 docutils==0.11 sphinx-rtd-theme==0.1.5 +sphinxcontrib.httpdomain'