From 466eed46218ccf82f7d01629316603e59013d807 Mon Sep 17 00:00:00 2001
From: Eric Deutsch <edeutsch@users.noreply.github.com>
Date: Wed, 6 Apr 2022 23:08:13 -0700
Subject: [PATCH] Proposed implementation rules for KP allowlist and denylist

---
 ImplementationRules.md | 82 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/ImplementationRules.md b/ImplementationRules.md
index 6378ead3..949e1a2f 100644
--- a/ImplementationRules.md
+++ b/ImplementationRules.md
@@ -72,3 +72,85 @@ The terms MUST, SHOULD, MAY are used as defined in RFC 2119  https://tools.ietf.
   large (e.g., if the client specified `MONDO:0000001: disease or disorder`), the server SHOULD
   return a runtime error gracefully.
 
+## Specifying permitted and excluded KPs to an ARA
+- The proper syntax for specifying or excluding specific KPs to consult to an ARA MUST be done
+  via a `constraint` on a QEdge. The following is a complete Query example that disallows the
+  use of SemMedDB:
+
+```
+{
+  "message": {
+    "query_graph": {
+      "edges": {
+        "e01": {
+          "object": "n0",
+          "subject": "n1",
+          "predicates": [
+            "biolink:entity_negatively_regulates_entity"
+          ],
+          "constraints": [
+            {
+              "id": "biolink:knowledge_source",
+              "name": "knowledge source",
+              "value": "infores:semmeddb",
+              "not": true,
+              "operator": "=="
+            }
+          ]
+        }
+      },
+      "nodes": {
+        "n0": {
+          "ids": [
+            "NCBIGene:23221"
+          ],
+          "categories": [
+            "biolink:Gene"
+          ]
+        },
+        "n1": {
+          "categories": [
+            "biolink:Gene"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+A general "allowlist" SHOULD look like this:
+```
+      "constraints": [
+        {
+          "id": "biolink:knowledge_source",
+          "name": "knowledge source",
+          "value": [
+            "infores:rtx-kg2",
+            "infores:biothings-explorer",
+          ],
+          "operator": "=="
+        }
+      ],
+```
+
+(when the value is a list, the "==" operator works like a SQL "IN" clause, as clearly documented in the TRAPI yaml)
+
+Here is what a general "denylist" should look like:
+```
+      "constraints": [
+        {
+          "id": "biolink:knowledge_source",
+          "name": "knowledge source",
+          "value": [
+            "infores:rtx-kg2",
+            "infores:biothings-explorer",
+          ],
+          "not": true,
+          "operator": "=="
+        }
+      ],
+```
+
+(when the value is a list, the "==" operator combined with ' "not": true ' works like a SQL "NOT IN" clause, as clearly documented in the TRAPI yaml)
+