Improve consistency of match responses (fixes #1, #2) and various errata

api-schema · Jun 30, 2021 · e1fc277 · e1fc277
1 parent 39438c2
commit e1fc277
Showing 12 changed files with 149 additions and 152 deletions.
diff --git 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/<matchRequest>
+|*Request Endpoint*|`/v1/matchRequests/<matchRequest>``
 |*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
@@ -1,13 +1,17 @@
 {
   "$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",
   "properties": {
     "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" ]
 }
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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" ]