Today we're releasing **WOLS v1.2.0**, the most significant update to the WeMush Open Labeling Standard since its initial launch. This release is special because it was shaped entirely by real-world integration feedback from the WeMush cultivation tracking platform. This release includes: - **WOLS Specification v1.2.0** — the open standard itself - **@wemush/wols v1.2.0** — TypeScript/JavaScript library - **wols v1.2.0** — Python library ## What's WOLS?

New to WOLS? Expand for background.

WOLS (WeMush Open Labeling Standard) is an open specification for encoding specimen data in QR codes and digital labels for mushroom cultivation and research. It enables growers, researchers, and labs to share specimen data in a standardized, interoperable format—regardless of which software they use. The specification is open source under CC BY 4.0, and the official libraries are Apache 2.0.

## The Story Behind v1.2.0 When we set out to integrate `@wemush/wols` into the WeMush platform for production use, we discovered gaps between the theoretical specification and practical implementation needs. Rather than working around these issues privately, we decided to contribute our learnings back to the open standard. Here's what we learned and how v1.2.0 addresses each challenge. --- ## What's New in v1.2.0 ### 1. Flexible ID Format Validation **The Problem:** The v1.0 spec required IDs to match `wemush:[a-z0-9]+`, but most platforms use ULIDs or UUIDs as primary keys. This forced awkward workarounds like storing original IDs in custom fields. **The Solution:** v1.2.0 introduces configurable ID validation modes. ```typescript import { validateSpecimen } from '@wemush/wols'; // Accept ULIDs after the wemush: prefix const result = validateSpecimen(specimen, { idMode: 'ulid' }); // Accept UUIDs after the wemush: prefix const result = validateSpecimen(specimen, { idMode: 'uuid' }); // Accept any non-empty string (for maximum flexibility) const result = validateSpecimen(specimen, { idMode: 'any' }); // Or provide a custom validator const result = validateSpecimen(specimen, { customIdValidator: (id) => /^wemush:[A-Z0-9]{26}$/.test(id) }); ``` ```python from wols import validate_specimen from wols.core import IdMode # Accept ULIDs after the wemush: prefix result = validate_specimen(specimen, id_mode=IdMode.ULID) # Accept UUIDs after the wemush: prefix result = validate_specimen(specimen, id_mode=IdMode.UUID) # Accept any non-empty string result = validate_specimen(specimen, id_mode=IdMode.ANY) ``` ### 2. Type Alias System **The Problem:** WOLS defines 5 specimen types (CULTURE, SPAWN, SUBSTRATE, FRUITING, HARVEST), but platforms often have 15+ types like LIQUID_CULTURE, GRAIN_SPAWN, AGAR, etc. **The Solution:** A built-in type alias registry with 20+ common aliases. ```typescript import { registerTypeAlias, resolveTypeAlias, mapToWolsType } from '@wemush/wols'; // Built-in aliases work automatically resolveTypeAlias('LIQUID_CULTURE') // Returns 'CULTURE' resolveTypeAlias('GRAIN_SPAWN') // Returns 'SPAWN' resolveTypeAlias('PRIMORDIA') // Returns 'FRUITING' // Register custom aliases for your platform registerTypeAlias('MYCELIUM_BLOCK', 'SUBSTRATE'); // Map from user-friendly names mapToWolsType('Liquid Culture') // Returns 'CULTURE' ``` ```python from wols.type_aliases import ( resolve_type_alias, register_type_alias, map_to_wols_type, ) from wols.models.enums import SpecimenType # Built-in aliases work automatically resolve_type_alias("LIQUID_CULTURE") # Returns "CULTURE" resolve_type_alias("GRAIN_SPAWN") # Returns "SPAWN" # Register custom aliases for your platform register_type_alias("MYCELIUM_BLOCK", SpecimenType.SUBSTRATE) # Map from user-friendly names map_to_wols_type("Liquid Culture") # Returns SpecimenType.CULTURE ``` ### 3. Generation Format Flexibility **The Problem:** Different communities use different notation for filial generations: F1, G1, or just "1". The v1.0 spec only accepted `F{n}` format. **The Solution:** Accept and normalize multiple formats. ```typescript import { normalizeGeneration, isValidGeneration } from '@wemush/wols'; // All these inputs are now valid isValidGeneration('F2') // true isValidGeneration('G2') // true isValidGeneration('2') // true isValidGeneration('P') // true (parental) // Normalize to your preferred format normalizeGeneration('G2', 'filial') // Returns 'F2' normalizeGeneration('3', 'filial') // Returns 'F3' normalizeGeneration('F1', 'numeric') // Returns '1' ``` ```python from wols.generation import ( normalize_generation, is_valid_generation, GenerationFormat, ) # All these inputs are now valid is_valid_generation("F2") # True is_valid_generation("G2") # True is_valid_generation("2") # True is_valid_generation("P") # True (parental) # Normalize to your preferred format normalize_generation("G2", GenerationFormat.FILIAL) # Returns "F2" normalize_generation("3", GenerationFormat.FILIAL) # Returns "F3" normalize_generation("F1", GenerationFormat.NUMERIC) # Returns "1" normalize_generation("P", GenerationFormat.NUMERIC) # Returns "0" ``` ### 4. Reserved `_meta` Namespace **The Problem:** During import/export operations, platforms need to preserve metadata like original IDs or source system identifiers. Storing these in the `custom` field felt wrong since they're implementation details, not user data. **The Solution:** A reserved `_meta` namespace that's preserved through all operations but excluded from validation. ```typescript const specimen = createSpecimen({ type: 'CULTURE', species: 'Pleurotus ostreatus', strain: 'Blue Oyster', _meta: { sourceId: '01HQWK3R4S5T6V7W8X9Y0Z', sourceSystem: 'wemush-platform', importedAt: '2026-01-26T10:30:00Z', schemaVersion: '2.0' } }); // _meta is preserved through encryption, serialization, etc. const encrypted = await encryptSpecimen(specimen, { key: password }); const decrypted = await decryptSpecimen(encrypted, { key: password }); console.log(decrypted._meta.sourceId); // Still there! ``` ```python from wols import create_specimen, encrypt_specimen, decrypt_specimen from wols.models.enums import SpecimenType specimen = create_specimen( type=SpecimenType.CULTURE, species="Pleurotus ostreatus", strain="Blue Oyster", meta={ "sourceId": "01HQWK3R4S5T6V7W8X9Y0Z", "sourceSystem": "wemush-platform", "importedAt": "2026-01-26T10:30:00Z", } ) # _meta is preserved through encryption encrypted = encrypt_specimen(specimen, key=password) decrypted = decrypt_specimen(encrypted, key=password) print(decrypted.meta["sourceId"]) # Still there! ``` ### 5. Convenience API Methods **The Problem:** The `parseCompactUrl()` function returns a discriminated union, which is correct but requires verbose error handling for simple cases. **The Solution:** Two convenience variants. ```typescript import { parseCompactUrl, parseCompactUrlOrThrow, parseCompactUrlOrNull } from '@wemush/wols'; // Original API - full control over error handling const result = parseCompactUrl(url); if (result.success) { console.log(result.data); } else { console.error(result.error); } // New: Throw on error (for when you want exceptions) try { const specimen = parseCompactUrlOrThrow(url); } catch (e) { // Handle error } // New: Return null on error (for optional chaining) const specimen = parseCompactUrlOrNull(url); if (specimen) { // Use specimen } ``` ```python from wols import parse_compact_url from wols.exceptions import WolsParseError # Standard API - returns ParseResult result = parse_compact_url(url) if result.success: print(result.data) else: print(result.error) # Python-idiomatic: use try/except try: specimen = parse_compact_url(url, raise_on_error=True) except WolsParseError as e: print(f"Parse failed: {e}") ``` ### 6. Environment Detection Utilities **The Problem:** WOLS supports both browser (Web Crypto API) and server (Node.js crypto) encryption. Detecting the environment correctly is surprisingly tricky, especially with bundlers, SSR, and edge runtimes. **The Solution:** Robust, tested environment detection. ```typescript import { isServer, isBrowser, isWebWorker, isDeno, isBun, getRuntimeEnvironment, isCryptoSupported, supportsWebCrypto } from '@wemush/wols'; // Check environment if (isServer()) { // Use Node.js crypto } else if (isBrowser()) { // Use Web Crypto API } // Check crypto availability if (isCryptoSupported()) { const encrypted = await encryptSpecimen(specimen, { key: password }); } // Get detailed runtime info console.log(getRuntimeEnvironment()); // 'node' | 'browser' | 'webworker' | 'deno' | 'bun' | 'unknown' ``` ### 7. Migration Utilities **The Problem:** As WOLS evolves, specimens created with older versions need to be upgraded. Without tooling, this burden falls on every integrating platform. **The Solution:** Built-in version comparison and migration. ```typescript import { compareVersions, isOutdated, migrate, registerMigration } from '@wemush/wols'; // Check versions compareVersions('1.0.0', '1.2.0') // -1 (older) isOutdated('1.0.0') // true (vs current library version) // Register custom migrations registerMigration('1.0.0', '1.1.0', (specimen) => { // Transform specimen from 1.0.0 to 1.1.0 format return { ...specimen, version: '1.1.0' }; }); // Migrate specimens const updated = migrate(oldSpecimen); // Automatically chains migrations ``` ```python from wols.migration import ( compare_versions, is_outdated, migrate, register_migration, ) # Check versions compare_versions("1.0.0", "1.2.0") # -1 (older) is_outdated("1.0.0") # True # Register custom migrations def migrate_1_0_to_1_1(specimen): specimen.version = "1.1.0" return specimen register_migration("1.0.0", "1.1.0", migrate_1_0_to_1_1) # Migrate specimens updated = migrate(old_specimen) # Chains migrations automatically ``` ### 8. Extended Growth Stages (Research-Grade Precision) **The Problem:** The v1.0 spec defined only 4 growth stages (INOCULATION, COLONIZATION, FRUITING, HARVEST), but research and commercial operations track more granular lifecycle phases—like distinguishing between post-inoculation incubation and visible colonization, or tracking pin formation separately from full fruiting. **The Solution:** WOLS v1.2.0 expands to 7 research-grade growth stages. ```typescript import { GROWTH_STAGES, type GrowthStage } from '@wemush/wols'; const stages: GrowthStage[] = [ 'INOCULATION', // Initial spore/culture introduction 'INCUBATION', // Post-inoculation, pre-visible growth (NEW) 'COLONIZATION', // Active mycelial growth 'PRIMORDIA', // Pin initiation / hyphal knots (NEW) 'FRUITING', // Fruiting body development 'SENESCENCE', // End-of-life monitoring (NEW) 'HARVEST' // Final harvest stage ]; // Use in specimen tracking const specimen = createSpecimen({ type: 'FRUITING', species: 'Pleurotus ostreatus', growthStage: 'PRIMORDIA', // Track pin initiation! notes: 'First pins visible, day 14' }); ``` **Why This Matters for Researchers:** | Stage | Scientific Use Case | | ----- | ------------------- | | INCUBATION | Monitor post-inoculation period before visible growth; track contamination window | | PRIMORDIA | Precise timing of pin initiation; correlate with environmental conditions | | SENESCENCE | Research end-of-life characteristics; spore production timing | --- ## Breaking Changes **None!** WOLS v1.2.0 is fully backward compatible. All v1.0.0 and v1.1.0 specimens continue to work. New features are opt-in. --- ## Roadmap: What's Next? ### v1.3.0 (Q2 2026) — IoT & Analytics - **IoT Sensor Integration**: Standard schema for temperature, humidity, CO₂, and light sensor data - **Advanced Analytics**: Yield prediction fields and quality metrics - **Supply Chain**: Multi-party verification and custody transfer tracking ### v2.0.0 (Q3-Q4 2026) — Maturity - Performance-optimized encoding formats - Blockchain verification hooks - Standards body submission (ANSI/ISO alignment) --- ## Start Using v1.2.0 **Install:** ```bash # TypeScript/JavaScript npm install @wemush/wols # Python pip install wols # or uv add wols ``` **Read the specification:** - [SPECIFICATION.md](https://github.com/wemush/open-standard/blob/main/SPECIFICATION.md) - [ROADMAP.md](https://github.com/wemush/open-standard/blob/main/ROADMAP.md) **Migrate existing specimens:** ```typescript import { isOutdated, migrate } from '@wemush/wols'; // Check if specimens need upgrading if (isOutdated(specimen.version)) { const updated = migrate(specimen); // Save updated specimen } ``` **Contribute:** We welcome feedback, bug reports, and PRs. Start a [GitHub Discussion](https://github.com/wemush/open-standard/discussions) or check out our [CONTRIBUTING.md](https://github.com/wemush/open-standard/blob/main/CONTRIBUTING.md). --- ## Thank You WOLS v1.2.0 wouldn't exist without real-world integration challenges. Thank you to everyone who tested early versions and provided feedback. This is how open standards should work: built by the community, for the community. Happy cultivating! 🍄 --- *The WeMush Open Labeling Standard is licensed under CC BY 4.0 (specification) and Apache 2.0 (code). Built with 🍄 by cultivators, for cultivators.*

Loading WeMush...

WOLS v1.2.0: Real-World Integrations Shape the Open Standard