initial commit; redacted out personal details for privacy concerns :-)

entitlements.org

@@ -0,0 +1,503 @@
+* Introduction
+The purpose of this document is to investigate possible User Interaction designs for Decode task 4.4.
+More specifically the focus is on investigating how the user of a decode wallet grants permission to decode application for a specific set of personal data.
+   
+* Data Model
+** Example wallet profile
+
+This sample wallet profile datastructure consists of multiple contexts.
+No assumptions are made about ontology for now so mention of existing e.g. skos/foaf, 
+everything is in the decode namespace which is well known across applications.
+
+Each context has a name and groups on or more properties that consist of a well known type and a value.
+A type can be part of more than one context. 
+#+name: profile 
+#+begin_src js :results output
+  var profile = {
+      contexts : 
+      [
+          {
+             title : "personal",
+              properties : 
+              [
+                  {
+                      type : "decode:name",
+                      value: "Taco van Dijk"
+                  },
+                  {
+                      type : "decode:email",
+                      value : "[REDACTED]"
+                  },
+                  {
+                      type: "decode:address",
+                      value: "[REDACTED]"
+                  },
+                  {
+                      type: "decode:phone",
+                      value : "[REDACTED]"
+                  }
+              ]
+          },
+          {
+              title: "professional",
+              properties : 
+              [
+                  {
+                      type : "decode:name",
+                      value : "Taco van Dijk"
+                  },
+                  {
+                      type : "decode:email",
+                      value : "taco@waag.org"
+                  },
+                  {
+                      type : "decode:address",
+                      value : "St. Antoniesbreestraat 69" 
+                  }
+              ]
+          }
+      ]
+  };
+  process.stdout.write(JSON.stringify(profile));
+#+end_src
+
+#+RESULTS: profile
+: {"contexts":[{"title":"personal","properties":[{"type":"decode:name","value":"Taco van Dijk"},{"type":"decode:email","value":"taco@yavin4.nl"},{"type":"decode:address","value":"Spaarndammerdijk 194"},{"type":"decode:phone","value":"0641639180"}]},{"title":"professional","properties":[{"type":"decode:name","value":"Taco van Dijk"},{"type":"decode:email","value":"taco@waag.org"},{"type":"decode:address","value":"St. Antoniesbreestraat 69"}]}]}
+
+*** Things to further investigate
+    - Make a big list of possible property types (at least properties that are used in Gebied Online)
+    - Make a big list of possible context names
+    - Create a generator that seeds profiles with random contexts from the aforementioned lists.
+    - Apply default weights to each property type, for example a high weight for the type ssn, and low for twitter@.
+ 
+** Example request 
+
+This sample application request consists of an application name, a set of required property types and a set of optional property types.
+
+#+name: request
+#+BEGIN_SRC js :results output
+  var request = {
+      application : "decodeapp:facebook",
+      required : ["decode:name", "decode:email", "decode:address"],
+      optional : ["decode:phone"]
+  }
+  var data = JSON.stringify(request) + "\n";
+  process.stdout.write(data);
+#+END_SRC
+
+#+RESULTS: request
+: {"application":"decodeapp:facebook","required":["decode:name","decode:email","decode:address"],"optional":["decode:phone"]}
+
+*** Things to further investigate
+    - Create a generator that seeds a request with random required and optional property types
+    - Add a 'sphere / context type' to each application. So tha
+
+* Data Comparison
+During the interaction we want to give the user insight into a couple of things;
+- How does the requested set of properties relate to the different contexts? How well does a context match to the request?
+- What would it mean for the context if the request was accepted? How many / which properties would have to be added to the context in order to fulfill the request?
+- What would it mean for the cumulative weight of the context?
+
+In below ruby code a comparison is made by on creating the intersection and its inverse between the request and each context.
+
+#+name: diff
+#+BEGIN_SRC ruby :noweb yes :var profile_data=profile :var request_data=request :results value file 
+  require 'json'
+  require 'nokogiri' #for creating xml
+
+  request = JSON.parse(request_data)
+  profile = JSON.parse(profile_data)
+
+  context_diffs = []
+  profile["contexts"].each do | context |
+    requested = request["required"] + request["optional"]
+    available = context["properties"].map {|p| p["type"]}
+
+    intersect = available & requested
+    except = requested - available
+    diff = {:context => context["title"], :intersect => intersect, :except => except}
+
+    context_diffs << diff
+  end
+
+  <<xml>>
+#+END_SRC
+
+#+RESULTS: diff
+[[file:diff.xml]]
+
+*** Things to further investigate
+    - Calculate the weight of each context before and after giving permission
+
+NOTE: We export to file diff.xml here for easy parsing in processing.js below.
+
+#+name: xml 
+#+BEGIN_SRC ruby :exports none
+  # unfortunately processing.js doesn't support json yet, so we have to use xml
+  doc = Nokogiri::XML::Builder.new do |xml|
+  xml.result {
+    xml.request { 
+      xml.application request["application"] 
+      xml.required {
+        request["required"].each do |p| xml.property p end
+      } 
+      xml.optional {
+        request["optional"].each do |p| xml.property p end
+      }
+    }
+    xml.diffs {
+      context_diffs.each do |diff|
+       xml.diff {
+        xml.contextName diff[:context]
+        xml.intersect {
+          diff[:intersect].each do |p| xml.property p end
+        }
+        xml.except {
+          diff[:except].each do |p| xml.property p end
+        }
+       }
+      end
+    }
+  }
+  end
+  path = "diff.xml"
+  File.write(path, doc.to_xml) 
+  path
+  #+END_SRC
+
+/de relatieve grootte van de cirkel kan zijn op basis van hoeveel data je erin hebt. 
+personal is size 4, professional size 3
+request is size 3
+
+* Visualization
+
+We want to visualize the following things;
+- The request with the application name and it's size / quality (Who's asking what)
+- The different contexts with it's name and size / quality relative to the request. (What would it mean to accept?)
+
+Per the design of Dyne, we want to use color to indicate the relation between the request and each context.
+- 
+
+#+name: glue 
+#+BEGIN_SRC processing :exports none 
+class Request
+{
+  public String application;
+  public String[] required_properties;
+  public String[] optional_properties;
+
+  public Request(String app, String[] req, String[] opt)
+  {
+    this.application = app;
+    this.required_properties = req;
+    this.optional_properties = opt;
+  }
+}
+
+class Diff
+{
+  public String context;
+  public String[] intersect;
+  public String[] except;
+
+  public Diff(String ctx, String[] intersect, String[] except)
+  {
+    this.context = ctx;
+    this.intersect = intersect;
+    this.except = except;
+  } 
+}
+
+XMLElement doc = new XMLElement(this, 'diff.xml');
+//create typed versions because this is java :-(
+void parseRequest(xml)
+{
+  XMLElement req = xml.getChild(0);
+  String name = req.getChild(0).getContent();
+  String[] required = new String[req.getChild(1).getChildCount()];
+  String[] optional = new String[req.getChild(2).getChildCount()];
+  
+  for (int i = 0; i < required.length; i++) {
+    required[i] = req.getChild(1).getChild(i).getContent();
+  }
+
+  for (int i = 0; i < optional.length; i++) {
+    optional[i] = req.getChild(2).getChild(i).getContent();
+  }
+
+  Request r = new Request(name,required,optional);
+  return r;
+}
+
+//create typed versions because this is java :-(
+void parseDiffs(xml)
+{
+  XMLElement diffsEl = xml.getChild(1);
+  Diff[] diffs = new Diff[diffsEl.getChildCount()];
+  for(int i = 0; i < diffs.length; i++)
+  {
+    String contextName = diffsEl.getChild(i).getChild(0).getContent();
+    String[] intersects = new String[diffsEl.getChild(i).getChild(1).getChildCount()];
+    String[] except = new String[diffsEl.getChild(i).getChild(2).getChildCount()];
+    
+    for(int j = 0; j < intersects.length; j++)
+    {
+      intersects[j] = diffsEl.getChild(i).getChild(1).getChild(j).getContent();
+    }
+
+    for(int j = 0; j < except.length; j++)
+    {
+      except[j] = diffsEl.getChild(i).getChild(2).getChild(j).getContent();
+    }
+
+    Diff diff = new Diff(contextName,intersects,except);
+    diffs[i] = diff;
+  }
+  return diffs;
+}
+#+END_SRC
+
+** Request
+#+name: draw_request
+#+BEGIN_SRC processing :noweb yes
+<<glue>>
+Request r = parseRequest(doc);
+Diff[] d = parseDiffs(doc);
+//set up font for labels
+//PFont label_font = createFont("Arial",16,true);
+//textFont(label_font,12);
+
+//draw the difference for each context with the request
+size(200,200);
+background(0);
+noFill();
+stroke(255);
+ellipse(56, 46, 55, 55);
+//fill(255);
+text(r.application, 10, 10);
+#+END_SRC
+
+#+RESULTS: draw_request
+#+BEGIN_EXPORT html
+<script src="processing.js"></script>
+ <script type="text/processing" data-processing-target="ob-358673b6aca53ef65765ed4baecf23b8c3889682">
+class Request
+{
+  public String application;
+  public String[] required_properties;
+  public String[] optional_properties;
+
+  public Request(String app, String[] req, String[] opt)
+  {
+    this.application = app;
+    this.required_properties = req;
+    this.optional_properties = opt;
+  }
+}
+
+class Diff
+{
+  public String context;
+  public String[] intersect;
+  public String[] except;
+
+  public Diff(String ctx, String[] intersect, String[] except)
+  {
+    this.context = ctx;
+    this.intersect = intersect;
+    this.except = except;
+  } 
+}
+
+XMLElement doc = new XMLElement(this, 'diff.xml');
+//create typed versions because this is java :-(
+void parseRequest(xml)
+{
+  XMLElement req = xml.getChild(0);
+  String name = req.getChild(0).getContent();
+  String[] required = new String[req.getChild(1).getChildCount()];
+  String[] optional = new String[req.getChild(2).getChildCount()];
+  
+  for (int i = 0; i < required.length; i++) {
+    required[i] = req.getChild(1).getChild(i).getContent();
+  }
+
+  for (int i = 0; i < optional.length; i++) {
+    optional[i] = req.getChild(2).getChild(i).getContent();
+  }
+
+  Request r = new Request(name,required,optional);
+  return r;
+}
+
+//create typed versions because this is java :-(
+void parseDiffs(xml)
+{
+  XMLElement diffsEl = xml.getChild(1);
+  Diff[] diffs = new Diff[diffsEl.getChildCount()];
+  for(int i = 0; i < diffs.length; i++)
+  {
+    String contextName = diffsEl.getChild(i).getChild(0).getContent();
+    String[] intersects = new String[diffsEl.getChild(i).getChild(1).getChildCount()];
+    String[] except = new String[diffsEl.getChild(i).getChild(2).getChildCount()];
+    
+    for(int j = 0; j < intersects.length; j++)
+    {
+      intersects[j] = diffsEl.getChild(i).getChild(1).getChild(j).getContent();
+    }
+
+    for(int j = 0; j < except.length; j++)
+    {
+      except[j] = diffsEl.getChild(i).getChild(2).getChild(j).getContent();
+    }
+
+    Diff diff = new Diff(contextName,intersects,except);
+    diffs[i] = diff;
+  }
+  return diffs;
+}
+Request r = parseRequest(doc);
+Diff[] d = parseDiffs(doc);
+//set up font for labels
+//PFont label_font = createFont("Arial",16,true);
+//textFont(label_font,12);
+
+//draw the difference for each context with the request
+size(200,200);
+background(0);
+noFill();
+stroke(255);
+ellipse(56, 46, 55, 55);
+//fill(255);
+text(r.application, 10, 10);
+</script> <canvas id="ob-358673b6aca53ef65765ed4baecf23b8c3889682"></canvas>
+#+END_EXPORT
+
+** Contexts
+   How do we visulize each context? Intend to do this in processing too.
+#+name: draw_context
+#+BEGIN_SRC processing :noweb yes
+<<glue>>
+Request r = parseRequest(doc);
+Diff[] d = parseDiffs(doc);
+//set up font for labels
+//PFont label_font = createFont("Arial",16,true);
+//textFont(label_font,12);
+
+//draw the difference for each context with the request
+size(200,200);
+background(0);
+noFill();
+stroke(255);
+ellipse(56, 46, 55, 55);
+//fill(255);
+text(d[0].context, 10, 10);
+#+END_SRC
+
+#+RESULTS: draw_context
+#+BEGIN_EXPORT html
+<script src="processing.js"></script>
+ <script type="text/processing" data-processing-target="ob-efa176753d914243c7a44088a4a08201dd1f5913">
+class Request
+{
+  public String application;
+  public String[] required_properties;
+  public String[] optional_properties;
+
+  public Request(String app, String[] req, String[] opt)
+  {
+    this.application = app;
+    this.required_properties = req;
+    this.optional_properties = opt;
+  }
+}
+
+class Diff
+{
+  public String context;
+  public String[] intersect;
+  public String[] except;
+
+  public Diff(String ctx, String[] intersect, String[] except)
+  {
+    this.context = ctx;
+    this.intersect = intersect;
+    this.except = except;
+  } 
+}
+
+XMLElement doc = new XMLElement(this, 'diff.xml');
+//create typed versions because this is java :-(
+void parseRequest(xml)
+{
+  XMLElement req = xml.getChild(0);
+  String name = req.getChild(0).getContent();
+  String[] required = new String[req.getChild(1).getChildCount()];
+  String[] optional = new String[req.getChild(2).getChildCount()];
+  
+  for (int i = 0; i < required.length; i++) {
+    required[i] = req.getChild(1).getChild(i).getContent();
+  }
+
+  for (int i = 0; i < optional.length; i++) {
+    optional[i] = req.getChild(2).getChild(i).getContent();
+  }
+
+  Request r = new Request(name,required,optional);
+  return r;
+}
+
+//create typed versions because this is java :-(
+void parseDiffs(xml)
+{
+  XMLElement diffsEl = xml.getChild(1);
+  Diff[] diffs = new Diff[diffsEl.getChildCount()];
+  for(int i = 0; i < diffs.length; i++)
+  {
+    String contextName = diffsEl.getChild(i).getChild(0).getContent();
+    String[] intersects = new String[diffsEl.getChild(i).getChild(1).getChildCount()];
+    String[] except = new String[diffsEl.getChild(i).getChild(2).getChildCount()];
+    
+    for(int j = 0; j < intersects.length; j++)
+    {
+      intersects[j] = diffsEl.getChild(i).getChild(1).getChild(j).getContent();
+    }
+
+    for(int j = 0; j < except.length; j++)
+    {
+      except[j] = diffsEl.getChild(i).getChild(2).getChild(j).getContent();
+    }
+
+    Diff diff = new Diff(contextName,intersects,except);
+    diffs[i] = diff;
+  }
+  return diffs;
+}
+Request r = parseRequest(doc);
+Diff[] d = parseDiffs(doc);
+//set up font for labels
+//PFont label_font = createFont("Arial",16,true);
+//textFont(label_font,12);
+
+//draw the difference for each context with the request
+size(200,200);
+background(0);
+noFill();
+stroke(255);
+ellipse(56, 46, 55, 55);
+//fill(255);
+text(d[0].context, 10, 10);
+</script> <canvas id="ob-efa176753d914243c7a44088a4a08201dd1f5913"></canvas>
+#+END_EXPORT
+
+*** Things to further investigate
+    - How do we show relation between request and each context with color?
+    - Can we use distance as well as color to indicate the relation?
+    - Can we use size of the circle to indicate the weight, or use badges?
+
+* Interaction
+We intend to investigate this in Processing as well.
+
+*** Things to further investigate
+    - How does the end user actually accept the request? Is it by dragging the request onto the context?
+    - How does the end user decline the request?