An open-source specification for encoding cultivation specimen data in machine-readable QR codes. Vendor-agnostic. Privacy-preserving. Research-grade.
🍄 Read the Full Specification | 📖 View Online | 🌐 WeMush Platform | 💬 Join the Discussion
The global mushroom industry is worth $50 billion but operates on spreadsheets and paper notebooks. There's no standardization, no interoperability, and no way to share cultivation insights across organizations.
WOLS fixes this.
┌─────────────────┐
│ QR Code Label │ ← Scan with any device
└────────┬────────┘
│
↓
┌─────────────────────────────────────────┐
│ Complete Specimen History: │
│ • Species & strain │
│ • Growth stage & timeline │
│ • Environmental conditions │
│ • Substrate composition │
│ • Harvest yields │
│ • Lineage & genetics │
└─────────────────────────────────────────┘- 🏭 Commercial Farms: Regulatory compliance and traceability
- 🔬 Research Labs: Reproducible experiments and data sharing
- 🏠 Home Cultivators: Track what works and optimize yields
- ♻️ Circular Economy: Prove sustainability claims with verifiable data
- 🤝 Equipment Manufacturers: Integrate tracking into products
import { generateLabel } from '@wemush/wols';
const label = await generateLabel({
species: "Pleurotus ostreatus",
strain: "Blue Oyster PoHu",
type: "SUBSTRATE",
stage: "COLONIZATION",
created: new Date().toISOString(),
});
// label.qrDataUrl → QR code as PNG data URL
// label.json → Full specimen datafrom wols import parse_label, scan_qr_code
# Scan QR code from image
specimen_data = scan_qr_code("path/to/qr_code.png")
# Or parse raw data
specimen = parse_label(qr_code_data)
print(f"Species: {specimen.species}")
print(f"Stage: {specimen.stage}")
print(f"Created: {specimen.created}")- No licensing fees - Free forever
- No vendor lock-in - Works with any platform
- Community-driven - Governance by steering committee
- Public data option: Share openly for research
- Encrypted data option: Protect proprietary strains
- Cryptographic signatures: Verify authenticity
- Complete lineage tracking: Parent → child relationships
- Environmental data: Temp, humidity, CO₂, light
- Substrate composition: Reproducible formulations
- Statistical analysis ready: Export to CSV, JSON, or SQL
- Custom namespaces: Add organization-specific fields
- Multiple encoding formats: Compact, embedded, or encrypted
- API-first design: Integrate with IoT sensors, equipment, or software
| Platform | WOLS Support | Link |
|---|---|---|
| WeMush | ✅ Native | wemush.com |
| [Your Platform?] | [Submit PR] | [Your link] |
Want to add your platform/library? See Contributing Guide
interface SpecimenLabel {
// Required
id: string; // Unique identifier
version: string; // Spec version (e.g., "1.0.0")
type: SpecimenType; // CULTURE | SPAWN | SUBSTRATE | FRUITING
species: string; // Scientific name
stage: GrowthStage; // Current growth stage
created: string; // ISO 8601 timestamp
// Optional
strain?: string; // Strain identifier
genetics?: GeneticsInfo; // Lineage tracking
batchId?: string; // Batch/cohort identifier
organization?: string; // Organization ID
custom?: Record<string, any>; // Extensible fields
signature?: string; // Cryptographic signature
}Compact (for small labels):
wemush://v1/clx1a2b3c4?s=POSTR&st=COLONIZATION&t=1734307200Embedded (most common):
{
"v": "1.0.0",
"id": "clx1a2b3c4",
"type": "SUBSTRATE",
"species": "Pleurotus ostreatus",
"strain": "Blue Oyster",
"stage": "COLONIZATION",
"created": "2025-12-16T10:30:00Z"
}Encrypted (proprietary strains):
wemush://v1/encrypted/clx1a2b3c4?e={payload}&sig={signature}WOLS is open source. WeMush Platform is proprietary.
This specification and all reference implementations are open source and free to use. You can:
✅ Build your own platform using WOLS ✅ Generate labels using the libraries ✅ Integrate WOLS into your products ✅ Fork and modify as needed
The WeMush Platform (https://wemush.com) is a proprietary implementation of WOLS that offers:
- Free tier with unlimited specimen tracking
- Premium features (ML, IoT, API, etc.)
- Professional support
- Hosted infrastructure
Why this model?
Open standards drive adoption. Proprietary platforms drive sustainability. This model ensures WOLS succeeds long-term while WeMush can continue investing in advanced features.
Other companies are welcome to build competing platforms. We believe the best implementation wins, and we're confident WeMush will be that implementation.
Problem: "Which substrate gives me the best yields?"
Solution:
- Print WOLS labels for each substrate bag
- Scan to log growth observations
- Compare yields across different recipes
- Reproduce the winner
Problem: "Food safety audit requires complete cultivation history"
Solution:
- QR code on retail packaging
- Customer scans → sees full history
- Proves organic, local, or sustainable claims
- Regulatory compliance in one scan
Problem: "Can't replicate experimental results from published paper"
Solution:
- WOLS label encodes exact parameters
- QR code in research paper
- Other labs scan → perfect replication
- Accelerates scientific progress
We welcome contributions from:
- 🌾 Growers: Use cases, feedback, testing
- 💻 Developers: Code, documentation, bug fixes
- 🔬 Researchers: Academic input, validation
- 🏭 Industry: Equipment integration, standards alignment
- Join the Discussion: GitHub Discussions
- Report Issues: GitHub Issues
- Submit Changes: Pull Request Guide
- Improve Docs: Every page has an "Edit" button
| Type | Description | Examples |
|---|---|---|
| 🐛 Bug Fix | Fix errors in spec or code | Typos, broken links, incorrect examples |
| ✨ Enhancement | Improve existing features | Better examples, clearer docs |
| 🎉 New Feature | Propose spec additions | New fields, encoding formats |
| 📚 Documentation | Write guides or tutorials | How-to articles, translations |
| 💬 Discussion | Start conversations | Use cases, design questions |
📋 Read Full Contributing Guide →
The WOLS specification is governed by a steering committee that reviews proposals and manages releases.
Current Members:
- Mark Beacom (Chair) - WeMush Foundation
- [Open seat] - Industry Representative
- [Open seat] - Academic Representative
- [Open seat] - Community Representative
Want to join? Apply here
- Submit issue describing proposed change
- Community discussion (14 days)
- Steering committee review
- RFC (Request for Comments) draft
- Final review and vote
- Merge and release
| Organization | Type | Use Case | Since |
|---|---|---|---|
| Mush Ohio | Commercial Farm | Production tracking | 2025 |
| [Your org?] | [Type] | [Use case] | [Year] |
Using WOLS? Add your organization →
If you use WOLS in research, please cite:
@techreport{beacom2025wols,
title={WeMush Open Labeling Standard: A Vendor-Agnostic Specification for Cultivation Specimen Tracking},
author={Beacom, Mark},
year={2025},
institution={WeMush Foundation},
url={https://github.com/wemush/open-standard}
}- ⭐ Star this repo to follow updates
- 👀 Watch releases for version announcements
- 📧 Join mailing list for monthly updates
- 🔔 Enable notifications for important discussions
Specification & Documentation: Creative Commons Attribution 4.0 International (CC BY 4.0)
You are free to:
- ✅ Share — copy and redistribute
- ✅ Adapt — remix, transform, build upon
- ✅ Commercial use — use in commercial products
Code Examples: Code snippets in this documentation may also be used under the Apache License 2.0 for easy integration into your projects.
Reference Implementations: Official client libraries (in separate repositories) are licensed under the Apache License 2.0.
WOLS was created by Mark Beacom (Veteran, 2025 FVC Fellow, 2025 TSTI Fellow) and is supported by:
- Farmer Veteran Coalition - Supporting veteran agriculture
- Transatlantic Sustainability Transition Initiative - EU-US innovation collaboration
- Open-source community - Contributors worldwide
Special thanks to early adopters, beta testers, and everyone providing feedback.
- ✅ Core specification released
- ✅ JavaScript/TypeScript library
- ✅ Python library (beta)
- ✅ Reference implementation (WeMush platform)
- 🚧 IoT sensor integration spec
- 🚧 Blockchain verification option
- 🚧 Image metadata standard
- 🚧 Multi-language translations
- 📋 Extended field data support
- 📋 Advanced genetic encoding
- 📋 Supply chain integration
- 📋 Carbon tracking standard
Q: Do I need to pay to use WOLS? A: No. WOLS is free forever. CC BY 4.0 license means zero licensing fees.
Q: Can I use WOLS with my existing software? A: Yes. WOLS is vendor-agnostic and designed for interoperability.
Q: What if I want to add custom fields?
A: Use the custom namespace. All implementations support extensibility.
Q: Is this only for mushrooms? A: No. WOLS works for any biological specimen tracking. Cannabis, hemp, plants, etc.
Q: Who owns the data encoded in WOLS labels? A: The cultivator who generated it. WOLS is just a format specification.
Q: How do I report security issues? A: Email [email protected] (PGP key available)
Q: If the standard is open, can competitors copy WeMush? A: They can support the WOLS standard, but not copy our platform. Think Android (open) vs Google Pixel (proprietary but best implementation).
Q: Do I have to buy WeMush consumables to use the platform? A: No. The free tier works with any WOLS-compliant labels, including ones you generate yourself.
Q: Why not fully open-source everything? A: Sustainability. Open-source projects need funding. By keeping the platform proprietary while open-sourcing the standard, we ensure long-term investment in both.
Q: What if WeMush goes out of business? A: The standard lives on. Your data is exportable. Other platforms can continue supporting WOLS. That's the power of open standards.
Q: Can I use WOLS without the WeMush platform? A: Yes! Use the open-source libraries to generate labels, store data however you want, build your own tools. WOLS is completely independent.
- ⭐ Star this repository - Increases visibility
- 🐛 Report bugs - Help improve quality
- 💻 Contribute code - Build the future
- 📢 Spread the word - Share with your network
- 💬 Join discussions - Shape the roadmap
WOLS development is supported by:
Project Lead: Mark Beacom Email: [email protected] Website: https://wemush.com GitHub: @wemush LinkedIn: Mark Beacom Twitter: @wemush