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_ID] = {
  name: '',
  label: '',
  color: '',
  displayVariable: '',
  iconVariant: {},
  variables: {},
};

Each entry in the node object defines a node "type" (such as "person", "friend", "place", or "venue"). The type is identified by a NODE_TYPE_ID key. This ID may equal the name for simplicity. All references to the node type elsewhere in the protocol will use this key/ID as an identifier.

This object contains multiple properties, defining various attributes of this node.

• "name": Required. A short, readable name that identifies the node type to users in Architect.
• "label": Required. A human readable label for this node type. For example, a node with name "health_venue" may use "Health Venue".
• "variables": Required. See below.
• "displayVariable": [recommended] Used to tell Network Canvas which variable to use for the visual representation of the node, if it does not have a "label" property set directly. If not defined, Network Canvas will attempt to find another text variable to use. If defined, this value must be a string corresponding to one of the keys in the variables object (see below).
• "color": [optional] Allows the user to override automatic color sequencing and specify a specific value in the color sequence for this node type
• "iconVariant": [optional] Used to define the icon shown when creating a new node of this type.

Variables

variableRegistry.node[NODE_TYPE_ID].variables[VARIABLE_ID] = {
  name: '',
  type: '',
  label: '',
  description: '',
  validation: {},
}

An object describing a variable for a node type.

• "name": Required. The variable name to use when referring to a node of this type, for example when exporting data.
• "type": A valid variable type. Valid variable types can be found here.
• "label": A human-readable, short label for this variable
• "description": A human-readable description for this variable
• "validation:: Validation rules (see below)

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.

Edge type definitions

Edge types are defined in a format similar to Node types; however, variables is not required, and node-specific properties such as "displayVariable" are not permitted.

variableRegistry.edge[EDGE_TYPE_ID] = {
  name: '',
  label: '',
}

Stages

Required. Must contain at least one stage object.

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

• "id": Required. A string that uniquely identifies this stage in the collection of stages.
• "type": Required. One of: NameGenerator, NameGeneratorList, NameGeneratorAutoComplete, OrdinalBin, Sociogram, or Information. See interfaces.
• "label": Required. A string that is displayed to the user for this stage
• Either "prompts" or "items" is required; each defines content for the stage
  • "items" is required if type is "Information". See Information interface.
  • "prompts" is required for all other types. Each prompt definition is specific to the type.
• "form": A string that identifies a form to use for node creation and editing on this stage. If defined, a form definition must exist with that name
• "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.