diff --git a/id-match-api.adoc b/id-match-api.adoc index 8653867..bbd0645 100644 --- a/id-match-api.adoc +++ b/id-match-api.adoc @@ -4,6 +4,7 @@ TAP Identity Match Protocol :Revision: v1.0.0 :toc: macro :!toc-title: +:toclevels: 3 **** {revision} {date} @@ -479,11 +480,14 @@ resolve the _Potential Matches_ response. "confidence":"85", "referenceId":"M219488003", "explanation":"Family name exact match, given name initial match", - "attributes": + "sorRecords": [ { - "sor":"HRMS", - "record":{ + "meta": { + "sorLabel":"Student", + "sorId":"089010023" + }, + "sorAttributes":{ "identifiers":[ { "type":"sor", @@ -505,7 +509,10 @@ resolve the _Potential Matches_ response. } }, { - "sor":"Alumni", + "meta": { + "sor":"Alumni", + "sorId":"A330-200" + }, "record":{ "identifiers":[ { @@ -542,11 +549,14 @@ resolve the _Potential Matches_ response. { "confidence":"71", "referenceId":"M523441767", - "attributes": + "sorRecords": [ { - "sor":"guest", - "record": { + "meta":{ + "sorLabel":"guest", + "sorId":"pl388" + }, + "sorAttributes": { "identifiers":[ { "type":"sor", @@ -586,29 +596,34 @@ resolve the _Potential Matches_ response. }, { "referenceId":"new", - "attributes": + "sorRecords": [ { - "sor":"SIS", - "identifiers":[ - { - "type":"sor", - "identifier":"971194843" - } - ] - "names":[ - { - "type":"official", - "given":"Pat", - "family":"Lee" - } - ], - "telephoneNumbers":[ - { - "type":"mobile", - "number":"8185551234" - } - ] + "meta": { + "sorLabel":"SIS", + "sorId":"971194843" + }, + "sorAttibutes":{ + "identifiers":[ + { + "type":"sor", + "identifier":"971194843" + } + ] + "names":[ + { + "type":"official", + "given":"Pat", + "family":"Lee" + } + ], + "telephoneNumbers":[ + { + "type":"mobile", + "number":"8185551234" + } + ] + } } ] } @@ -1012,57 +1027,60 @@ GET /v1/matchRequests?status=pending { "1009": { - "attributes": - { - "sor":"SIS", - "identifiers":[ - { - "type":"sor", - "identifier":"971194843" - } - ] - "names":[ - { - "type":"official", - "given":"Pat", - "family":"Lee" - } - ], - "telephoneNumbers":[ - { - "type":"mobile", - "number":"8185551234" - } - ] - }, - "requestTime":"2013-06-08T11:23:37Z" + "meta": { + "requestTime":"2013-06-08T11:23:37Z", + "sorLabel":"SIS", + "sorId":"971194843" + }, + "sorAttributes": { + "identifiers":[ + { + "type":"sor", + "identifier":"971194843" + } + ] + "names":[ + { + "type":"official", + "given":"Pat", + "family":"Lee" + } + ], + "telephoneNumbers":[ + { + "type":"mobile", + "number":"8185551234" + } + ] + } }, "1014": { - "attributes": - { - "sor":"HRMS", - "sorId":"914890374", - "identifiers":[ - { - "type":"sor", - "identifier":"089010023" - }, - { - "type":"network", - "identifier":"p5478" - } - ], - "names":[ - { - "type":"official", - "given":"Richard", - "family":"Hess" - } - ], - "ou":"Biology" - }, - "requestTime":"2013-06-08T11:23:37Z" + "meta": { + "requestTime":"2013-06-08T11:23:37Z", + "sorLabel":"HRMS", + "sorId":"914890374" + }, + "sorAttributes": { + "identifiers":[ + { + "type":"sor", + "identifier":"914890374" + }, + { + "type":"network", + "identifier":"p5478" + } + ], + "names":[ + { + "type":"official", + "given":"Richard", + "family":"Hess" + } + ], + "ou":"Biology" + } } } } @@ -1096,7 +1114,7 @@ Choices`. If the match request has been resolved, the server responds with a |===== |*Request Method* |`GET` -|*Request Endpoint*|`/v1/matchRequests/ +|*Request Endpoint*|`/v1/matchRequests/`` |*Request Body* |_none_ |*Response Codes* a| * `200 OK` * `403 Unauthorized` @@ -1231,8 +1249,7 @@ v1.0.0 * Initial release. * Changes from the https://spaces.at.internet2.edu/display/cifer/SOR-Registry+Strawman+ID+Match+API[ID Match API Strawman]: ** Removed `GET` option from Search Only Request. -** _Potential Match Found_ candidate attributes moved to `record`. -** Response format for _Current Values Request_ updated to include metadata. -** Clarified _Request Pending Match_ response. -** Removed options for returning identifiers and golden attributes in _Obtain - SOR Records_ response. +** Improved consistency across _Current Values Response_, _Match Request + Response_, and _Potential Match Found Response_ JSON documents. +** Removed options for returning identifiers and golden attributes as separate + entities in _Obtain SOR Records_ response. diff --git a/schema/json/current-values-response.json b/schema/json/current-values-response.json index 3b36ab7..973ff02 100644 --- a/schema/json/current-values-response.json +++ b/schema/json/current-values-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/current-values-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/current-values-response.json", "title": "TAP Identity Match Current Values Response", "description": "Current SoR values as known to the Identity Match engine", "type": "object", @@ -8,6 +8,10 @@ "meta": { "type": "object", "properties": { + "matchRequest": { + "description": "Match request identifier", + "type": "string" + }, "referenceId": { "description": "Match Reference Identifier, if assigned", "type": "string" @@ -21,14 +25,23 @@ "description": "Time request was resolved by the Identity Match service", "type": "string", "format": "date-time" + }, + "sorId": { + "description": "System of Record identifier for the match subject", + "type": "string" + }, + "sorLabel": { + "description": "Requesting System of Record", + "type": "string" } }, "required": [ "requestTime" ] }, "sorAttributes": { "description": "Attributes submitted by the System of Record to represent the subject", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" - } + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/properties/mixed" + }, + "additionalProperties": false }, "required": [ "meta", "sorAttributes" ] } \ No newline at end of file diff --git a/schema/json/error-response.json b/schema/json/error-response.json index 087acd1..96ad363 100644 --- a/schema/json/error-response.json +++ b/schema/json/error-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/error-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/error-response.json", "title": "TAP Identity Match Error Response", "description": "Error with request", "type": "object", diff --git a/schema/json/forced-reconciliation-request.json b/schema/json/forced-reconciliation-request.json index ce2d304..25e3423 100644 --- a/schema/json/forced-reconciliation-request.json +++ b/schema/json/forced-reconciliation-request.json @@ -1,13 +1,13 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/forced-reconciliation-request.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/forced-reconciliation-request.json", "title": "TAP Identity Match Forced Reconciliation Request", "description": "Identity Match Forced Reconciliation Request", "type": "object", "properties": { "sorAttributes": { "description": "Attributes submitted by the System of Record to represent the subject", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/properties/mixed" }, "referenceId": { "description": "Match Reference Identifier", diff --git a/schema/json/inventory-response.json b/schema/json/inventory-response.json index b22a2f6..8caf519 100644 --- a/schema/json/inventory-response.json +++ b/schema/json/inventory-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/inventory-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/inventory-response.json", "title": "TAP Identity Match Inventory of Requests Response", "description": "Inventory of SoR requests", "type": "object", diff --git a/schema/json/join-record-request.json b/schema/json/join-record-request.json index 754d1ce..41c498a 100644 --- a/schema/json/join-record-request.json +++ b/schema/json/join-record-request.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/join-record-request.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/join-record-request.json", "title": "TAP Identity Match Join Record Request", "description": "Identity Match Join Records Request", "type": "object", @@ -15,13 +15,13 @@ "uniqueItems": true }, "identifiers": { - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/attribute-dictionary.json#/definitions/identifiers", + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/definitions/identifiers", "minItems": 1, "uniqueItems": true }, "golden": { "description": "Golden attributes, as maintained by the Identity Match engine", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/properties/mixed" } }, "required": [ "referenceIds" ] diff --git a/schema/json/match-request-response.json b/schema/json/match-request-response.json index 54d5cf2..189dff8 100644 --- a/schema/json/match-request-response.json +++ b/schema/json/match-request-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/match-request-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/match-request-response.json", "title": "TAP Identity Match Match Request Response", "description": "Match requests", "type": "object", @@ -10,37 +10,8 @@ "type": "object", "patternProperties": { "^[0-9]+$": { - "type": "object", - "properties": { - "attributes": { - "description": "An array of SoR records for this candidate", - "type": "array", - "items": { - "type": "object", - "properties": { - "record": { - "description": "The attributes for this candidate as asserted by the System of Record", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" - } - } - } - }, - "referenceId": { - "description": "Match Reference Identifier, if assigned", - "type": "string" - }, - "requestTime": { - "description": "Time request was submitted by the System of Record", - "type": "string", - "format": "date-time" - }, - "resolutionTime": { - "description": "Time request was resolved by the Identity Match service", - "type": "string", - "format": "date-time" - } - }, - "required": [ "attributes" ] + "description": "Attributes submitted by the System of Record to represent the subject", + "$ref": "https://github.internet2.edu/raw/api-schema/id-match-api/draft/schema/json/current-values-response.json" } }, "additionalProperties": false diff --git a/schema/json/potential-match-external-response.json b/schema/json/potential-match-external-response.json index 88fac85..8ad37bf 100644 --- a/schema/json/potential-match-external-response.json +++ b/schema/json/potential-match-external-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/potential-match-external-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/potential-match-external-response.json", "title": "TAP Identity Match Potential Match (Externally Handled0) Response", "description": "Potential match(es) found for search request, but externally handled", "type": "object", diff --git a/schema/json/potential-match-response.json b/schema/json/potential-match-response.json index a693317..de6fc73 100644 --- a/schema/json/potential-match-response.json +++ b/schema/json/potential-match-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/potential-match-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/potential-match-response.json", "title": "TAP Identity Match Potential Match Found Response", "description": "Potential match(es) found for search request", "type": "object", @@ -17,44 +17,40 @@ "minimum": 1, "maximum": 100 }, - "referenceId": { - "description": "Match Reference Identifier, or the string 'new' to indicate the original request as a new record", - "type": "string" - }, "explanation": { "description": "A human readable explanation as to why this candidate was returned, to provide guidance to an administrator reviewing the request", "type": "string" }, - "attributes": { - "description": "An array of SoR records for this candidate", - "type": "array", - "items": { - "type": "object", - "properties": { - "record": { - "description": "The attributes for this candidate as asserted by the System of Record", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" - } - } - } - }, "golden": { "description": "The golden record for this candidate (for coordinated implementations); if present, attributes may be empty", "type": "object", "properties": { "record": { "description": "The attributes for this candidate as asserted by the System of Record", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/properties/mixed" } } }, "identifiers": { - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/attribute-dictionary.json#/definitions/identifiers", + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/definitions/identifiers", "minItems": 1, "uniqueItems": true }, + "referenceId": { + "description": "Match Reference Identifier, if assigned", + "type": "string" + }, + "sorRecords": { + "description": "An array of SOR records linked to this candidate", + "type": "array", + "items": { + "description": "Attributes submitted by the System of Record to represent the subject", + "$ref": "https://github.internet2.edu/raw/api-schema/id-match-api/draft/schema/json/current-values-response.json" + } + }, + "additionalProperties": false }, - "required": [ "referenceId", "attributes" ] + "required": [ "referenceId", "sorRecords" ] }, "minItems": 1, "uniqueItems": true diff --git a/schema/json/reassign-referenceid-request.json b/schema/json/reassign-referenceid-request.json index 52533c1..04db6ee 100644 --- a/schema/json/reassign-referenceid-request.json +++ b/schema/json/reassign-referenceid-request.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/reassign-referenceid-request.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/reassign-referenceid-request.json", "title": "TAP Identity Match Reassign Reference Identifier Request", "description": "Identity Match Reassign Reference Identifier Request", "type": "object", diff --git a/schema/json/referenceid-response.json b/schema/json/referenceid-response.json index c941df2..e700b09 100644 --- a/schema/json/referenceid-response.json +++ b/schema/json/referenceid-response.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/referenceid-response.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/referenceid-response.json", "title": "TAP Identity Match Unique Match Found Response", "description": "Unique match found for search request", "type": "object", @@ -10,13 +10,13 @@ "type": "string" }, "identifiers": { - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/attribute-dictionary.json#/definitions/identifiers", + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/definitions/identifiers", "minItems": 1, "uniqueItems": true }, "golden": { "description": "Golden attributes, as maintained by the Identity Match engine", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/properties/mixed" } }, "required": [ "referenceId" ] diff --git a/schema/json/standard-request.json b/schema/json/standard-request.json index f1d39d8..1781ad1 100644 --- a/schema/json/standard-request.json +++ b/schema/json/standard-request.json @@ -1,13 +1,13 @@ { "$schema": "https://json-schema.org/draft/2019-09/schema", - "$id": "https://github.internet2.edu/benno/id-match-api/tree/draft/schema/json/standard-request.json", + "$id": "https://github.internet2.edu/api-schema/id-match-api/blob/draft/schema/json/standard-request.json", "title": "TAP Identity Match Standard Request", "description": "Standard Identity Match Request", "type": "object", "properties": { "sorAttributes": { "description": "Attributes submitted by the System of Record to represent the subject", - "$ref": "https://github.internet2.edu/benno/core-schema/tree/draft/schema/json/core-schema.json#/properties/mixed" + "$ref": "https://github.internet2.edu/raw/api-schema/attribute-dictionary/blob/draft/schema/json/attribute-dictionary.json#/properties/mixed" } }, "required": [ "sorAttributes" ]