Preference Conditions Format

From wiki.gpii
Jump to: navigation, search

Overview

This page outlines the GPII-supported format for conditional preferences, which are declarative, extensible, and semantic in nature. The motivation for these features is described below.

Declarative

The format for conditional preferences is declarative: it is a standard data structure that can be operated on by any programming language. Rather than being a programming language itself, which requires parsers and code generators to be reliably interpreted and written, this declarative format uses JSON to represent the operations required to evaluate a conditional preference. As a result, it's straightforward to read and operate, and substantially easier to programmatically generate.

Semantic and Extensible

Users will employ a variety of tools to create, edit, and manage their preferences sets. In many cases, they'll interact with a wizard or preferences editor that will be carefully designed to provide a highly usable experience using language that the user can relate to. In order to provide user interfaces for editing conditions, we'll need a system that is semantic—one that closely captures the user's terminology and concepts. While the use of low-level Boolean operators for defining conditions is appealingly flexible, it significantly limits the usability of the interfaces we can provide to the user, since this approach lacks higher-level semantics.

With this in mind, this page defines a format that includes higher level concepts ("in the range of", "in the morning", etc.), each corresponding to an operator term in the registry. These terms will be bound by the run time evaluator to function or method calls within a native implementation. This set of operators can be extended by defining new operator terms in the Registry.

Multiple Sets Scoped by Conditions

Users will have the ability to create a set of preferences that apply under certain conditions. As a result, all preferences will be nested inside named containers that correspond with the user's named sets. The user's default (or "base") set will be stored under the key "gpii-default". Conditions will only occur at "top level" qualifying an entire preferences object (in the same way that preferences are, behind the scenes in the preferences server, classified in a document into ontologies--e.g. ).

Conditions and operators take the form of named terms associated with a JSON object ("spec") describing their arguments. These terms will be bound by the runtime system to a function that will evaluate the condition or operator. Operators are identified by the special keyword "operator".

The goal is that this format should be amenable to translate into a Transfomer-compatible format in the future.

Terminology

A condition evaluator is a function that:

  1. Is bound to a particular condition term id
  2. Takes an arbitrary condition "value"
  3. Takes a piece of relevent "context data" (e.g. device reporter information, time of day, environmental reporter data, etc.)
  4. Returns an appropriate value (e.g. a boolean if the condition is successfully matched)

An operator is a function that:

  1. Is bound to a particular operator term URI
  2. Takes an "operands" array as an argument
  3. May contain sub-operators
  4. Defers to a set of condition evaluators to evaluate its conditions
  5. Returns an appropriate value (e.g. a boolean for a boolean operator)

A priority is a IEEE 754 floating point value that:

  1. Represents the priority for a particular collections of preferences in the case that multiple contexts match equally
  2. Is optional
    1. discussion at page with the proposal about priorities
  3. Values over 1024 are reserved for "system-level" prioritization

Datatypes

Work in progress, please see: Proposal for Declarative Preference Conditions Datatypes until a final decision is made.

Examples

These examples are based on the wireframes designed for the Preferences Management Tool, which allow users to create different sets preferences for different contexts.


Simplified Form With Implicit Operator

{
    "contexts": {
        "gpii-default": {
            "name": "Default preferences",
            "preferences": {
                "http://registry.gpii.net/common/fontSize": 12
            }
        },

        "nighttime-at-home": {
            "name": "Nighttime at home",

            "preferences": {
                "http://registry.gpii.net/common/fontSize": 24
            },

            "conditions": [
                {
                    "type": "http://registry.gpii.net/conditions/timeInRange",
                    "from": "18:00",
                    "to": "06:00"
                    "inputPath": "http://registry\\.gpii\\.net/common/environment/temporal\\.time"
                },
                {
                    "type": "http://registry.gpii.net/conditions/inRange",
                    "min": 700,
                    "inputPath": "http://registry\\.gpii\\.net/common/environment/visual\\.illuminance"
                 }
            ],

            // This contains metadata that is specific to the settings of the 
            // "nighttime-at-home" contextualized NP set.
            "metadata": [
                {
                    "type": "provenance",
                    "scope": ["http://registry.gpii.net/common/fontSize"],
                    "source": "snapshotter"
                }, 
                {
                    "type": "required":
                    "scope": ["*"] // meaning, "all preferences written in this context"
                }
            ],

            "priority": 100
        }
    },

    // Metadata that applies to all preferences, regardless of which 
    // context they're in.
    "metadata": [
        {
            "type": "doNotShare",
            "scope": [ "http://registry.gpii.net/common/fontSize"],
            "applications": [
                "com.facebook",
                "com.twitter"
            ]
        }
    ]
}

Expanded, Advanced Form with Operators

{
    "contexts": {
        "gpii-default": {
            "name": "Default preferences",
            "preferences": {
                "http://registry.gpii.net/common/fontSize": 12
            }
        },

        "nighttime-at-home": {
           "name": "Nighttime at home",

           "preferences": {
               "http://registry.gpii.net/common/fontSize": 24
           },

           "conditions": {
               "operator": {
                   "type": "fluid.transforms.booleanOp",
                   "op": "||",
                   "operands": [
                       {
                           "type": "http://registry.gpii.net/conditions/timeOfDay",
                           "range": {
                               "start": 1730,
                               "end": 730
                           }
                       },
                       {
                           "type": "http://registry.gpii.net/conditions/location",
                           "gps": {
                               "lat": "79.3N",
                               "long": "74.9W"
                           },
                           "range": "200m"
                       }
                   ]
               }
           },

           "priority": 0.5,

            // This contains metadata that is specific to the settings of the 
            // "nighttime-at-home" contextualized NP set.
            "metadata": [
                {
                    "type": "provenance",
                    "scope": ["http://registry.gpii.net/common/fontSize"],
                    "source": "snapshotter"
                }, 
                {
                    "type": "required":
                    "scope": ["*"] // meaning, "all preferences written in this context"
                }
            ],

        }
    },

    // Metadata that applies to all preferences, regardless of which 
    // context they're in.
    "metadata": [
        {
            "type": "doNotShare",
            "scope": [ "http://registry.gpii.net/common/fontSize"],
            "applications": [
                "com.facebook",
                "com.twitter"
            ]
        }
    ]
}