Breathwork Schema

An open source JSON schema for defining breathwork exercises in a standardized format.

Overview

The Breathwork Schema provides a universal, open source JSON schema for defining breathwork exercises. Our mission is to create a standard that empowers developers, practitioners, and applications to share and build upon a common foundation.

This schema allows different apps and devices to share and use the same breathwork exercises seamlessly, providing a stable foundation for developers to build new tools and experiences.

Features

• Universal Format: Compatible with any programming language and platform
• Comprehensive: Covers timing, instructions, benefits, categorization, and media
• Extensible: Designed with future growth in mind
• Validated: JSON Schema validation ensures data integrity
• Open Source: CC0 1.0 Universal license - public domain

Quick Start

Example Exercise File

Create a file with the .breath extension:

{
  "id": "4-7-8-breathing",
  "name": "4-7-8 Breathing",
  "description": "A powerful calming technique that helps reduce anxiety and improve sleep quality.",
  "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.",
  "timings": {
    "in": 4,
    "hold": 7,
    "out": 8
  },
  "cycles": 4,
  "recommendedDuration": "5-10 minutes",
  "benefits": [
    "Reduces Stress",
    "Improves Sleep Quality",
    "Manages Cravings",
    "Controls Anger Responses"
  ],
  "category": "Relaxation",
  "difficulty": "Beginner",
  "tags": ["anxiety", "sleep", "calm"],
  "media": {
    "image": "4-7-8-breathing.png",
    "audioGuide": "4-7-8-breathing.mp3"
  },
  "metadata": {
    "author": "Dr. Andrew Weil",
    "source": "Traditional Pranayama",
    "dateCreated": "2024-01-15",
    "version": "1.0.0"
  }
}

Validation

You can validate your breathwork files against the schema using any JSON Schema validator:

# Using ajv-cli
npm install -g ajv-cli
ajv validate -s schema.json -d your-exercise.breath

# Using Python
pip install jsonschema
python -c "
import json
from jsonschema import validate
with open('schema.json') as f: schema = json.load(f)
with open('your-exercise.breath') as f: data = json.load(f)
validate(data, schema)
print('Valid!')
"

Schema Properties

Required Properties

Property	Type	Description
id	string	Unique identifier (lowercase, dashes only)
name	string	Human-readable exercise name
description	string	Brief summary of the exercise
instructions	string	Step-by-step guide
timings	object	Breath timing parameters
cycles	integer	Default number of breath cycles

Timing Object

Property	Type	Required	Description
in	integer	✓	Inhalation duration (seconds)
out	integer	✓	Exhalation duration (seconds)
hold	integer		Hold after inhalation (seconds)
holdAfterOut	integer		Hold after exhalation (seconds)

Optional Properties

Property	Type	Description
recommendedDuration	string	Suggested practice time
benefits	array	List of exercise benefits
category	string	Exercise category (see categories below)
tags	array	Additional search tags
difficulty	string	Beginner, Intermediate, or Advanced
media	object	Associated media files
metadata	object	Additional information

Categories

• Relaxation - Calming and stress-reducing exercises
• Energizing - Invigorating and awakening practices
• Focus - Concentration and mental clarity
• Sleep - Practices for better sleep
• Stress Relief - Anxiety and tension reduction
• Meditation - Mindfulness and spiritual practices
• Recovery - Post-exercise or healing
• Performance - Athletic or mental performance
• Anxiety Management - Specific anxiety techniques
• Other - Miscellaneous or specialized practices

File Format

Files using this schema should use the .breath extension to clearly indicate they contain breathwork exercise data.

Implementation Examples

JavaScript/Node.js

import fs from 'fs';
import Ajv from 'ajv';

// Load schema and exercise
const schema = JSON.parse(fs.readFileSync('schema.json', 'utf8'));
const exercise = JSON.parse(fs.readFileSync('4-7-8-breathing.breath', 'utf8'));

// Validate
const ajv = new Ajv();
const validate = ajv.compile(schema);
const valid = validate(exercise);

if (!valid) {
  console.log(validate.errors);
}

Python

import json
from jsonschema import validate, ValidationError

# Load schema and exercise
with open('schema.json') as f:
    schema = json.load(f)
    
with open('4-7-8-breathing.breath') as f:
    exercise = json.load(f)

# Validate
try:
    validate(exercise, schema)
    print("Exercise is valid!")
except ValidationError as e:
    print(f"Validation error: {e.message}")

Contributing

We welcome contributions to improve and extend the Breathwork Schema! Here's how you can help:

Ways to Contribute

1. Suggest Schema Improvements: Open an issue to discuss new properties or modifications
2. Add Example Exercises: Create example .breath files for different techniques
3. Improve Documentation: Help make the schema more accessible
4. Report Issues: Found a problem? Let us know!

Development Setup

1. Fork the repository
2. Clone your fork
3. Make your changes
4. Test with example files
5. Submit a pull request

Guidelines

• Follow semantic versioning for schema changes
• Ensure backward compatibility when possible
• Include examples for new properties
• Update documentation for changes
• Test thoroughly before submitting

Versioning

This schema follows Semantic Versioning:

• Major version (x.0.0): Breaking changes to existing properties
• Minor version (0.x.0): New optional properties or categories
• Patch version (0.0.x): Bug fixes, documentation, or clarifications

Current version: 0.1.0

License

This work is licensed under CC0 1.0 Universal - effectively public domain. You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.

Community

• Issues: Report bugs or request features
• Discussions: Join the conversation
• Examples: See the examples/ directory for sample exercises

Related Projects

• Libre Breath - Website and documentation