Skip to content

protocol.json

Jump to bottom
Rebecca Madsen edited this page Feb 20, 2019 · 18 revisions

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: {},
  ego: {},
};

An object containing details of the fundamental node, edge, and ego 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: {},
  options: []
}

An object describing a variable for a node type.

  • "name": Required. Must be unique within this collection of variables. 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)
  • "options": Answer options for categorical & ordinal variable types (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.

options

A variable whose type is ordinal or categorical must define the available options for the variable in an options array.

Each option must define a string or numeric value. This may be done as part of an options object, which may also include a label that can be displayed to users. The following examples are all valid.

options: [ { label: '', value: '' } /*, ... */ ]
options: [ { value: '' } /*, ... */ ]
options: [ '' /*, ... */ ]
options: [ 0 /*, ... */ ]

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: '',
}

Ego definitions

Ego types are defined in a format similar to Node types; however, type is not used, and node-specific properties such as "displayVariable" and "color" are not used.

variableRegistry.ego = {
  label: '',
  variables: {},
};

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.
  • "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

Prompts

General Attributes:

  • "id": Required. Unique within this collection of prompts.
  • "text": Required. The prompt text displayed to the user.

Other interface types define more specific properties for their prompts.

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[FORM_NAME] = {
  title: '',
  entity: 'node',
  type: NODE_TYPE_ID,
  optionToAddAnother: true,
  fields: []
};

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

  • "title": Required.
  • "entity": Required. Entity 'node', 'edge', and 'ego' are supported.
  • "type": Optional. The type [of entity] to create. Required for 'node' and 'edge' entities, but not for 'ego'. A string ID matching a key in the variable registry.
  • "fields": Required. An array of field definitions. See below.
  • "optionToAddAnother": A boolean value; will present an option to the user to "create another" when submitting a form.
forms[FORM_NAME].fields = [{
  variable: VARIABLE_ID,
  component: '',
  label: '',
}]
  • "variable": Required. A string ID matching a key in the type's variable definitions, denoting an edge or node attribute.
  • "component": Required . See Input Types for all available component types. Hidden fields can be specified to automatically add static values to data.
  • "label": displayed to the user for this field

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.

Clone this wiki locally