Open Causal Graph Data Standard

Version 0.1 · December 2025 · superseded

0.1 was published as the tables below rather than as a machine-readable schema. One has since been written for it, so that documents produced against this version can still be validated: https://opencausal.org/causaljson/0.1/causaljson.schema.json. It documents 0.1 exactly as published, and unlike 0.2 it does not reject unknown fields, because 0.1 never said what a reader should do with them.

Overview

The Open Causal platform proposes a standardized JSON format for sharing and exchanging causal graphs of all types, including DAGs, ADMGs, and more. This data standard is designed to capture the essential components of causal graphs, including nodes, edges, and metadata, in a structured and machine-readable format. This data standard enables interoperability across different tools, platforms, and research workflows, making causal knowledge more accessible and machine-readable.

Schema Specification (version 0.1)

The complete JSON schema for specifying causal graphs includes metadata, node definitions, and edge definitions. Below is the full structure with all possible fields:

Complete JSON Structure

{
  "graph": {
    "id": "unique-identifier",
    "date": "2024-01-01T00:00:00Z",
    "title": "Graph Title",
    "description": "A description of the causal graph",
    "creator": {
      "name": "Creator Name",
      "orcid": "0000-0000-0000-0000"
    },
    "contributors": [
      {
        "name": "Contributor Name",
        "orcid": "0000-0000-0000-0001",
        "role": "author"
      }
    ],
    "licence": "cc-by-4.0",
    "type": "dag",
    "cyclicity": "acyclic",
    "related_publication": [
      {
        "doi": "10.1234/example",
        "title": "Related Publication Title",
        "year": 2024
      }
    ],
    "statistical_unit": "individual"
  },
  "nodes": [
    {
      "id": "node1",
      "name": "Treatment",
      "description": "The treatment or exposure variable",
      "position": {"x": 100, "y": 150},
      "causal_role": "exposure",
      "variable_type": "continuous",
      "time_point": "baseline",
      "structural_model": "linear",
      "ontology_ids": ["ONTOLOGY:12345"]
    },
    {
      "id": "node2",
      "name": "Outcome",
      "description": "The primary outcome",
      "position": {"x": 300, "y": 150},
      "causal_role": "outcome",
      "variable_type": "binary"
    }
  ],
  "edges": [
    {
      "source": "node1",
      "target": "node2",
      "type": "directed",
      "position": {"curve": 0.5},
      "sign": "positive"
    }
  ]
}

Field Definitions

Graph Object

Field	Type	Required	Description
id	string	Yes	Unique identifier for the graph. Should be URL-safe and immutable.
date	ISO 8601 datetime	Yes	Creation or last modified date of the graph in ISO 8601 format.
title	string	Yes	Human-readable title of the causal graph.
description	string	No	Detailed description of the graph, its context, and assumptions.
creator	object	Yes	Person who created the graph. Contains 'name' (required) and 'orcid' (optional).
contributors	array of objects	No	List of people who contributed to the graph with their roles.
licence	string	Yes	License under which the graph is distributed (e.g., 'CC BY 4.0', 'CC BY-SA 4.0').
type	enum	Yes	Graph type: 'dag' (Directed Acyclic Graph), 'cyclic' (with cycles), 'undirected', 'mixed'.
cyclicity	enum	Yes	Cyclicity status: 'acyclic', 'cyclic', or 'unknown'.
related_publication	array of objects	No	List of publications that discuss or use this causal graph.
statistical_unit	string	No	Unit of analysis for the graph (e.g., 'individual', 'household', 'population', 'time-series').

Nodes Array

Field	Type	Required	Description
id	string	Yes	Unique identifier for the node within the graph.
name	string	Yes	Human-readable name of the variable or concept.
description	string	No	Detailed description of what the node represents.
position	object {x, y}	No	X and Y coordinates for visualization. Allows tools to preserve layout.
causal_role	enum	No	Role in the causal structure: 'exposure', 'outcome', 'confounder', 'mediator', 'collider', 'other'.
variable_type	enum	No	Data type: 'binary', 'categorical', 'continuous', 'count', 'survival', 'other'.
time_point	string	No	Time point at which the variable is measured (e.g., 'baseline', 'month_6', 'follow-up').
structural_model	string	No	Assumed structural model: 'linear', 'nonlinear', 'multiplicative', 'threshold', 'other'.
ontology_ids	array of strings	No	References to ontologies (e.g., SNOMED-CT, UMLS, MeSH) for standardized variable definitions.

Edges Array

Field	Type	Required	Description
source	string	Yes	ID of the source (from) node.
target	string	Yes	ID of the target (to) node.
type	enum	Yes	Edge type: 'directed', 'undirected', 'bidirected', 'dashed' (unknown direction).
position	object	No	Visualization metadata for edge layout (e.g., curve parameter for curved edges).
sign	enum	No	Direction of effect: 'positive' (increases), 'negative' (decreases), 'unknown'.

Example:

{
  "graph": {
    "id": "12345678",
    "date": "2026-04-13T00:00:00Z",
    "title": "Ice Cream Sales and Drowning Deaths",
    "description": "A DAG showing that ice cream sales and drowning deaths are correlated due to a common cause (warm weather), not a direct causal relationship.",
    "creator": {
      "name": "Abdullah Ademoğlu",
      "orcid": "0000-0000-0000-0000"
    },
    "licence": "cc-by-4.0",
    "type": "dag",
    "cyclicity": "acyclic",
    "statistical_unit": "population"
  },
  "nodes": [
    {
      "id": "weather",
      "name": "Warm Weather",
      "description": "Temperature and seasonality (summer months)",
      "position": {"x": 50, "y": 50},
      "causal_role": "confounder",
      "variable_type": "continuous"
    },
    {
      "id": "ice_cream",
      "name": "Ice Cream Sales",
      "description": "Weekly ice cream sales in units sold",
      "position": {"x": 200, "y": 150},
      "causal_role": "exposure",
      "variable_type": "continuous"
    },
    {
      "id": "drowning",
      "name": "Drowning Deaths",
      "description": "Weekly drowning fatalities",
      "position": {"x": 350, "y": 150},
      "causal_role": "outcome",
      "variable_type": "count"
    }
  ],
  "edges": [
    {
      "source": "weather",
      "target": "ice_cream",
      "type": "directed",
      "sign": "positive"
    },
    {
      "source": "weather",
      "target": "drowning",
      "type": "directed",
      "sign": "positive"
    },
    {
      "source": "ice_cream",
      "target": "drowning",
      "type": "dashed"
    }
  ]
}

What changed in 0.2

The current version is CausalJSON 0.2. The largest differences: the people listed in the citation are authors (0.1 called them contributors, and called the uploader the creator); a node's display name is label rather than name; causal_role no longer includes confounder, mediator or collider, which are computed from the structure rather than declared; cyclicity is gone for the same reason; edge types are defined by their endpoint marks, with dashed replaced by undirected and the circle marks of partial ancestral graphs added; and every edge can carry a justification, with a separate excluded_edges array for relationships that were considered and ruled out.