protocol.json

Protocol.json

Overall Structure

let protocol = {
  name: '',
  lastModified: '',
  description: '',
  networkCanvasVersion: '',
  variableRegistry: {},
  externalData: {},
  forms: {},
  stages: []
}

Name

Required.

name = '';

Source of the canonical name of the protocol, irrespective of filename. This name is treated as the unique identifier of the protocol.

Variable Registry

Required. May be empty.

variableRegistry = {
  node: {},
  edge: {},
};

An object containing details of the fundamental node and edge types that are operated on within this interview, and any associated properties that these entities may have.

Node type definitions

variableRegistry.node[NODE_TYPE] = {
  name: '', // A field name that will be used (for example) when exporting data from the app
  label: '', // A human readable label for this node type. For example, a node type of "health_venue" may use "Health Venue".
  color: '', // [optional] Allows the user to override automatic color sequencing and specify a specific value in the color sequence for this node type
  displayVariable: '', // [optional] Used to tell network canvas which variable to use for the visual representation of the node.
  iconVariant: {}, // [optional] Used to define the icon shown when creating a new node of this type.
  variables: {}, // See below
};

Each named entry in the node key corresponds to an object representing a node "type" (such as "person", "friend", "place", or "venue"). This object contains multiple properties, defining various attributes of this node.

Variables

variableRegistry.node[NODE_TYPE].variables[VARIABLE_NAME] = {
  label: '', // A human readable short label for this variable.
  description: '', // A human readable description for this variable
  type: '', // A valid variable type. For types, see below.
  validation: {}, // Validation rules
}

An object describing a variable for a node of type NODE_TYPE. Valid variable types can be found here.

Validations

validation: {
  required: true,
  requiredAcceptsNull: true,
  minLength: 0,
  maxLength: 0,
  minValue: 0,
  maxValue: 0,
  minSelected: 0,
  maxSelected: 0
}

An object with zero or more properties having boolean or numeric values (see example) that describe the validations that should be applied during creation and editing.

Stages

Required. Must contain at least one stage object.

{
  "id": "",
  "type": "",
  "label": "",
  "form": "",
  "subject": {
    "entity": "",
    "type": ""
  },
  "panels": [],
  "prompts": []
}

• "type": one of NameGenerator, NameGeneratorList, NameGeneratorAutoComplete, OrdinalBin, Sociogram, or Information. See interfaces.
• "prompts": each prompt definition is specific to the type.
• "panels": may be defined for the Name Generator
• "subject": Defines the node type; see the documentation of Name Generator

Metadata

lastModified = 'YYYY-MM-DDTHH:mm:ss.sssZ';

Replaced version as the mechanism to determine the relative version of the protocol file. Format: ECMA-262 Date Time String. This field may be used to display a protocol's modification time to users.

description = '';

A short description of the protocol. Displayed to users.

details = '';

User facing field designed to be used for any additional information. The value of this property is shown on the new interview card for this protocol.

networkCanvasVersion = '';

Specifies the version of Network Canvas that this protocol was designed to work with. Semver format.

External Data

data = {};

The data key holds external data to be used within the interview. Essentially, it functions as a data repository for things outside of the interview that might nevertheless be brought into it. Examples of how this data might be brought into an interview are through node creation (a roster network is included in the data key, and the user selects a node from this network on a roster interface), or by displaying the data on a specific interface (for example displaying census tract data stored in the data key on a map interface).

Eventually we intend for it to be possible to have the data itself located elsewhere, with the data key merely containing a URI 'pointer' that can be resolved to access (or create) the data. This system would allow data to be dynamically loaded and created by other systems in response to interview variables. For example, a previous network could be downloaded and displayed in a side panel on a name generator, based on a participant ID.

Forms

forms = [];

Forms map variables defined in the registry to components. For example, a text variable might be mapped to an input component, and a boolean variable could be mapped to a toggle box, or a checkbox.

forms[NODE_TYPE] = { /* form definition */ };

By default, an interface will look for a form with the same name as the object type.

forms[NODE_TYPE].fields[].variable = 'firstName';

These variables are assumed to be children of the object type that is being created.

Hidden fields can be specified to automatically add static values to data. See Input Types for all available field types.

Dynamic value generation

To support use cases where arbitrary dynamic data should be created automatically, we plan to eventually support expression evaluation in a manner similar to custom node labeling.