📄 Protocol Definition Schema

All our problem goal's protocols are described in a json file. This json has an structured definition that all protocols must follow. This is what powers the protocol's states and transitions. This document describes the structure and constraints of the protocol_definition_schema.json file.

The schema is custom designed, but it follows the general conventions of JSON Schema. It uses defs, type, properties, items, required, additionalProperties, etc. If you want to expand on the schema, please keep that in mind, and try to adhere as much as possible to the JSON Schema conventions.

Overview

The schema defines a protocol with the following main components:

• States: Represents the various states that the problem goal could have. For each state, contains some state information and the interventions that should be created when transitioning into the state.
• Transitions: Defines how the protocol transitions between states.

---

Top-Level Properties

states (Required)

• Type: Array of objects
• Description: Defines the states in the protocol.

State Object Properties

Property	Type	Description	Required
name	string	The unique name of the state.	Yes
display_name	string	The human-readable name of the state. This is the value that will be displayed in the front end state dropdown.	Yes
severity	string	The severity level of the state. When a problem goal is in a state with stable severity, it will be sorted to the bottom of the problems list.	No
status	string	The status of the state. When transitioning to a state with status, it will try to change the problem goal's status to the one described here. Possible values: completed, canceled.	No
initial	boolean	Indicates whether this is the initial state. When evaluating a problem goal, if no rule is matched, it defaults to the initial state.	No
manual_transition_disabled	boolean	Indicates whether manual transitions are disabled for this state.	No
always_create_interventions_for	array	A list of trigger sources for which interventions should always be created when entering this state, regardless if the previous state == new state.	No
interventions	array	A list of interventions associated with this state.	No

Interventions Object Properties

Property	Type	Description	Required
type	string	The type of the intervention class without the module (e.g. CompleteForms).	Yes
role	string	The role of the user that will be assigned to the intervention.	No*
operation	string	The operation to perform. Possible values: create, upsert, update.	No
always_create_for	array	A list of trigger sources for which this intervention should always be created, regardless if the new state == old state.	No
deduplication_resolver	string	A custom resolver for deduplication logic. Currently supports: phq9_already_scheduled.	No
deduplication_key	string	A unique key to deduplicate interventions. When transitioning to a new state, if there is another intervention opened for that problem with the same deduplication_key, we skip creating it.	No
due_date	string	The due date for the intervention. Could be either a dynamic value (from the supported ones), or a date in unit.unit_type format (e.g. 1.month)	No*
custom_fields	object	Additional custom fields for the intervention.	No
deduplication_params	array	Parameters used for deduplication. This works as another deduplication method besides the deduplication_key. More details below.	No
recurrence	object	Defines recurrence settings for the intervention.	No
priority	string	The priority level of the intervention. Possible values: urgent, routine.	No

*Note: role and due_date are required unless the operation is update. For update operations, at least one of deduplication_key, deduplication_params, or deduplication_resolver must be provided.

Recurrence Object Properties

Property	Type	Description	Required
period	integer	The number of time units for the recurrence period. Must be at least 1.	No
period_unit	string	The time unit for the recurrence period. Possible values: days, weeks, months, years.	No

Deduplication Parameters Object Properties

Property	Type	Description	Required
fields	array	A list of fields used for deduplication. Can include strings or objects with custom_field.	Yes
states	array	A list of states relevant for deduplication. Could be scoped states (active, completed, canceled) or scoped (e.g. awaiting_results for a CompleteForms intervention)	No

Trigger Source Values

The following trigger sources are supported for always_create_interventions_for and always_create_for:

• TRIGGER_SOURCE:FORM_SUBMISSION:PHQ_9
• TRIGGER_SOURCE:FORM_SUBMISSION:INTAKE
• TRIGGER_SOURCE:FORM_SUBMISSION:HEALTH_ASSESSMENT
• TRIGGER_SOURCE:INTERVENTION_COMPLETION
• TRIGGER_SOURCE:PROBLEM_CREATION
• TRIGGER_SOURCE:READING_CREATION
• TRIGGER_SOURCE:PROBLEM_START
• TRIGGER_SOURCE:JOB
• TRIGGER_SOURCE:MANUAL_TRANSITION

---

transitions (Required)

• Type: Array of objects
• Description: Defines the transitions between states.

Transition Object Properties

Property	Type	Description	Required
from	array	A list of states from which the transition can occur.	No
to	string	The target state of the transition.	Yes
rule	object	A condition or group of conditions that must be satisfied for the transition to occur. Can be either a group, or a condition.	No
reason	string	The reason for the transition. This will be displayed in the problem goal's timeline in the front end.	Yes

---

Rule object options definitions

group

• Type: Object
• Description: Represents a group of conditions combined with a logical operator.

Properties

Property	Type	Description	Required
type	string	Must be "group".	Yes
operator	string	The logical operator for the group. Possible values: and, or.	Yes
conditions	array	A list of conditions or nested groups.	Yes

---

condition

• Type: Object
• Description: Represents a single condition that must be satisfied.

Properties

Property	Type	Description	Required
type	string	Must be "condition".	Yes
parameter	object	The parameter to evaluate. Described below.	Yes
operator	string	The operator to use for evaluation. Currently supported values: eq, neq, gt, lt, gte, lte, btw, lbtw, rbtw, in, nin, includes, not_includes, all_lt and all_gt.	Yes
value	any	The value to compare the parameter result against.	Yes

Parameter Object Properties

Property	Type	Description	Required
key	string	The data fetcher's query key. E.g. most_recent_form_score	Yes
args	object	Arguments for the data fetcher. E.g. "form_type": "PHQ9"	Yes

---

Example JSON

Real examples can be found in the protocol_definitions directory