A Schema for Breathwork

A community initiative to standardize breathwork practices and data. We're developing an open standard that will enable interoperability between apps, preserve traditional techniques, and make breathing practices more accessible. We're seeking input from the breathwork community to help finalize our first official release.

Example File

File: 4-7-8-breathing.breath

An example file for the "4-7-8 Breathing" technique, conforming to the schema.

4-7-8-breathing.breath

1{
2  "id": "4-7-8-breathing",
3  "name": "4-7-8 Breathing",
4  "description": "A powerful calming technique that helps reduce anxiety and improve sleep quality.",
5  "instructions": "Breathe in through your nose for 4 seconds, hold your breath for 7 seconds, and exhale completely through your mouth for 8 seconds. Repeat for the desired number of cycles.",
6  "timings": {
7    "in": 4,
8    "hold": 7,
9    "out": 8
10  },
11  "cycles": 4,
12  "recommendedDuration": "5-10 minutes",
13  "benefits": [
14    "Reduces Stress",
15    "Improves Sleep Quality",
16    "Manages Cravings",
17    "Controls Anger Responses"
18  ],
19  "category": "Relaxation",
20  "difficulty": "Beginner",
21  "tags": [
22    "anxiety",
23    "sleep",
24    "calm"
25  ],
26  "media": {
27    "image": "4-7-8-breathing.png",
28    "audioGuide": "4-7-8-breathing.mp3"
29  },
30  "metadata": {
31    "author": "Dr. Andrew Weil",
32    "source": "Traditional Pranayama",
33    "dateCreated": "2024-01-15",
34    "version": "1.0.0"
35  }
36}

The Schema Definition

Schema: .breath

This proposed JSON Schema defines the structure for breathwork exercise files. We're seeking feedback from practitioners and developers to refine this before our official v1.0 release.

breathwork-schema.json

1{
2  "$schema": "http://json-schema.org/draft-07/schema#",
3  "$id": "https://breathwork-schema.org/v0.1.0/schema.json",
4  "title": "Breathwork Exercise Schema",
5  "description": "A schema for defining breathwork exercises in a standardized format.",
6  "version": "0.1.0",
7  "type": "object",
8  "properties": {
9    "id": {
10      "type": "string",
11      "description": "Unique identifier for the exercise (e.g., '4-7-8-breathing').",
12      "pattern": "^[a-z0-9-]+$",
13      "minLength": 1,
14      "maxLength": 100
15    },
16    "name": {
17      "type": "string",
18      "description": "Human-readable name of the breathwork exercise.",
19      "minLength": 1,
20      "maxLength": 200
21    },
22    "description": {
23      "type": "string",
24      "description": "A short, descriptive summary of the exercise and its purpose.",
25      "minLength": 1,
26      "maxLength": 500
27    },
28    "instructions": {
29      "type": "string",
30      "description": "Clear, step-by-step guide for performing the exercise.",
31      "minLength": 1
32    },
33    "timings": {
34      "type": "object",
35      "description": "Timing parameters for a single breath cycle in seconds.",
36      "properties": {
37        "in": {
38          "type": "integer",
39          "description": "Duration for inhalation in seconds.",
40          "minimum": 1,
41          "maximum": 60
42        },
43        "hold": {
44          "type": "integer",
45          "description": "Duration to hold breath after inhalation in seconds.",
46          "minimum": 0,
47          "maximum": 120
48        },
49        "out": {
50          "type": "integer",
51          "description": "Duration for exhalation in seconds.",
52          "minimum": 1,
53          "maximum": 60
54        },
55        "holdAfterOut": {
56          "type": "integer",
57          "description": "Duration to hold breath after exhalation in seconds (optional).",
58          "minimum": 0,
59          "maximum": 120
60        }
61      },
62      "required": [
63        "in",
64        "out"
65      ],
66      "additionalProperties": false
67    },
68    "cycles": {
69      "type": "integer",
70      "description": "Default number of breath cycles for one complete round.",
71      "minimum": 1,
72      "maximum": 100
73    },
74    "recommendedDuration": {
75      "type": "string",
76      "description": "Suggested total time to perform the exercise (e.g., '5-10 minutes').",
77      "pattern": "^[0-9]+-?[0-9]* (minutes?|seconds?)$"
78    },
79    "benefits": {
80      "type": "array",
81      "description": "A list of benefits associated with the exercise.",
82      "items": {
83        "type": "string",
84        "minLength": 1,
85        "maxLength": 100
86      },
87      "minItems": 0,
88      "maxItems": 20,
89      "uniqueItems": true
90    },
91    "category": {
92      "type": "string",
93      "description": "Category of the exercise.",
94      "enum": [
95        "Relaxation",
96        "Energizing",
97        "Focus",
98        "Sleep",
99        "Stress Relief",
100        "Meditation",
101        "Recovery",
102        "Performance",
103        "Anxiety Management",
104        "Other"
105      ]
106    },
107    "tags": {
108      "type": "array",
109      "description": "Additional tags for categorization and search.",
110      "items": {
111        "type": "string",
112        "minLength": 1,
113        "maxLength": 50
114      },
115      "minItems": 0,
116      "maxItems": 10,
117      "uniqueItems": true
118    },
119    "difficulty": {
120      "type": "string",
121      "description": "Difficulty level of the exercise.",
122      "enum": [
123        "Beginner",
124        "Intermediate",
125        "Advanced"
126      ]
127    },
128    "media": {
129      "type": "object",
130      "description": "Media files associated with the exercise.",
131      "properties": {
132        "image": {
133          "type": "string",
134          "description": "Filename or URL for a representative image.",
135          "format": "uri-reference"
136        },
137        "audioGuide": {
138          "type": "string",
139          "description": "Filename or URL for an optional guided audio file.",
140          "format": "uri-reference"
141        },
142        "video": {
143          "type": "string",
144          "description": "Filename or URL for an optional instructional video.",
145          "format": "uri-reference"
146        }
147      },
148      "additionalProperties": false
149    },
150    "metadata": {
151      "type": "object",
152      "description": "Additional metadata about the exercise.",
153      "properties": {
154        "author": {
155          "type": "string",
156          "description": "Person or organization who created or documented this exercise."
157        },
158        "source": {
159          "type": "string",
160          "description": "Original source or tradition of the exercise."
161        },
162        "dateCreated": {
163          "type": "string",
164          "description": "Date when this exercise definition was created.",
165          "format": "date"
166        },
167        "version": {
168          "type": "string",
169          "description": "Version of this specific exercise definition.",
170          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
171        }
172      },
173      "additionalProperties": false
174    }
175  },
176  "required": [
177    "id",
178    "name",
179    "description",
180    "instructions",
181    "timings",
182    "cycles"
183  ],
184  "additionalProperties": false
185}

Property Reference

Property	Type	Description
id	string	Unique identifier for the exercise (lowercase, dashes only).
name	string	Human-readable name of the exercise.
description	string	A short summary of the technique and its purpose.
instructions	string	Clear, step-by-step guide for performing the exercise.
timings	object	Contains the duration in seconds for each phase of a breath cycle.
↳ in	integer	Inhalation duration (1-60 seconds).
↳ hold	integer	Breath hold duration after inhale (0-120 seconds).
↳ out	integer	Exhalation duration (1-60 seconds).
↳ holdAfterOut	integer	Optional breath hold duration after exhale (0-120 seconds).
cycles	integer	The default number of cycles to perform (1-100).
recommendedDuration	string	A human-readable suggested duration (e.g., "5-10 minutes").
benefits	array	A list of key benefits (up to 20 items).
category	string	Exercise category (Relaxation, Energizing, Focus, etc.).
difficulty	string	Difficulty level (Beginner, Intermediate, Advanced).
tags	array	Additional search tags (up to 10 items).
media	object	Optional links to image, audio, and video files.
metadata	object	Additional information like author, source, and version.

Join the Development

Why We Need Your Input

Help us create a standard that serves the entire breathwork community.

Practitioner Expertise: We need input from experienced breathwork teachers and practitioners to ensure completeness.

Real World Testing: Help us validate the schema against actual breathwork techniques and traditions.

Community Standards: Ensure the schema reflects the diverse approaches and needs of the breathwork community.

Developer Feedback: Technical input to make implementation seamless across platforms.

Goals for Version 1.0

What we're working toward for the official release.

Comprehensive Coverage: Support for all major breathwork techniques and traditions.

Practitioner Validated: Reviewed and approved by experienced breathwork professionals.

Developer Ready: Battle tested by app developers and tool creators.

Future Proof: Designed to evolve with the growing breathwork community.