zorath-env v0.3.3: Remote Schemas, Caching, and Team Configuration Sharing

zorath-env v0.3.3 is now available. This release adds remote schema support, allowing you to fetch schemas from HTTPS URLs instead of local files. Your team can now share a single schema across all projects, and CI/CD pipelines can validate against centralized configuration standards.

Release Highlights

• Remote schema support via HTTPS URLs for shared team configurations
• Automatic caching with 1-hour TTL for improved performance
• --no-cache flag to bypass cache when you need fresh schemas
• Remote extends for schema inheritance from URLs
• Security-first with HTTPS-only enforcement for remote schemas
• 100% backward compatible with existing local schema workflows

Remote Schema Support

Managing environment schemas across multiple projects is painful. Teams often copy schemas between repos, and they inevitably drift. With v0.3.3, you can point all your projects at a single remote schema.

Fetching Schemas from URLs

Use any HTTPS URL as your schema source:

# Validate against a schema hosted on GitHub
zenv check --schema https://raw.githubusercontent.com/your-org/config/main/env.schema.json

# Generate docs from a remote schema
zenv docs --schema https://config.example.com/schemas/api.schema.json

# Create .env.example from remote schema
zenv example --schema https://raw.githubusercontent.com/your-org/config/main/env.schema.json

All commands that accept --schema now support HTTPS URLs: check, diff, docs, and example.

Why Remote Schemas Matter

Before v0.3.3: Each project has its own copy of the schema. When requirements change, someone has to update every repo manually. Schemas drift, validation fails inconsistently, and onboarding new developers means explaining "which schema is the real one."

After v0.3.3: One schema, one source of truth. Update the central schema once, and every project validates against it automatically.

Practical Use Cases

Team Configuration Server:

# All team projects point to the same schema
zenv check --schema https://internal.example.com/schemas/backend.schema.json

GitHub Raw URLs:

Host your schema in a dedicated config repo and reference it directly:

# From a public repo
zenv check --schema https://raw.githubusercontent.com/your-org/env-schemas/main/production.schema.json

# From a private repo (requires auth token in URL or git credentials)
zenv check --schema https://raw.githubusercontent.com/your-org/private-config/main/env.schema.json

GitOps Pattern:

Version your schemas alongside infrastructure code. CI/CD pipelines pull the schema from the same branch as the code:

# GitHub Actions example
- name: Validate environment
  run: |
    zenv check --schema https://raw.githubusercontent.com/${{ github.repository }}/main/env.schema.json

Schema Caching

Remote schemas are cached locally to avoid network overhead on repeated runs. The cache uses a 1-hour TTL (time-to-live).

How Caching Works

1. First request fetches the schema from the URL
2. Schema is cached locally with a timestamp
3. Subsequent requests within 1 hour use the cached version
4. After 1 hour, the next request fetches a fresh copy

# First run: fetches from network
zenv check --schema https://example.com/schema.json
# Cached

# Second run (within 1 hour): uses cache, instant
zenv check --schema https://example.com/schema.json
# From cache

# After 1 hour: fetches fresh copy
zenv check --schema https://example.com/schema.json
# Refreshed

Cache Location

The cache is stored in your system's standard cache directory:

Platform	Cache Path
Linux	~/.cache/zenv/schemas/
macOS	~/Library/Caches/zenv/schemas/
Windows	%LOCALAPPDATA%\zenv\schemas\

Cache files are named using a hash of the URL, so different schemas don't conflict.

The --no-cache Flag

Sometimes you need to bypass the cache entirely. Use --no-cache to force a fresh fetch:

# Always fetch the latest schema (ignore cache)
zenv check --schema https://example.com/schema.json --no-cache

When to Use --no-cache

CI/CD Pipelines: Ensure you're validating against the latest schema, not a stale cached version:

# GitHub Actions
- name: Validate with fresh schema
  run: zenv check --schema ${{ env.SCHEMA_URL }} --no-cache

Testing Schema Changes: When you're updating a remote schema and want to verify changes immediately:

# Force fresh fetch after updating remote schema
zenv check --no-cache --schema https://raw.githubusercontent.com/org/repo/main/env.schema.json

Debugging Cache Issues: If validation behaves unexpectedly, bypass cache to rule out stale data:

zenv check --schema https://example.com/schema.json --no-cache

Remote Extends

Schemas can extend other schemas using the extends field. With v0.3.3, the base schema can be a remote URL:

{
  "extends": "https://raw.githubusercontent.com/your-org/base-schemas/main/common.schema.json",
  "API_KEY": {
    "type": "string",
    "required": true,
    "description": "Service-specific API key"
  }
}

Inheritance Chain

Remote extends supports the full inheritance chain:

1. Your local schema extends a remote base
2. The remote base can extend another remote schema
3. Up to 10 levels of inheritance (to prevent infinite loops)
4. Circular references are detected and rejected

# local.schema.json extends remote base.schema.json
# base.schema.json extends remote common.schema.json
# All three schemas are merged, child overrides parent
zenv check --schema local.schema.json

Mixed Local and Remote

You can mix local and remote schemas in the inheritance chain:

{
  "extends": "https://company.example.com/base-env.schema.json",
  "LOCAL_OVERRIDE": {
    "type": "string",
    "description": "Project-specific variable"
  }
}

Real-World Team Setup

Here's a complete workflow for setting up shared schemas across a team:

Step 1: Create a Central Schema Repository

Create a new repo (e.g., your-org/env-schemas) with your base schemas:

env-schemas/
  common.schema.json      # Shared by all projects
  backend.schema.json     # Extends common, adds DB/API vars
  frontend.schema.json    # Extends common, adds NEXT_PUBLIC vars

Step 2: Reference in Projects

Each project's env.schema.json extends the appropriate base:

{
  "extends": "https://raw.githubusercontent.com/your-org/env-schemas/main/backend.schema.json",
  "SERVICE_NAME": {
    "type": "string",
    "required": true,
    "description": "Unique name for this service"
  }
}

Step 3: CI/CD Validation

Add validation to your CI pipeline:

name: Validate Environment
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install zenv
        run: cargo install zorath-env
      - name: Validate .env schema
        run: zenv check --allow-missing-env --no-cache

Step 4: Update Schemas Centrally

When requirements change, update the central schema repo. All projects validate against the new schema automatically on their next CI run.

Security Considerations

HTTPS Only: Remote schemas must use HTTPS. HTTP URLs are rejected to prevent man-in-the-middle attacks that could tamper with your schema.

# This works
zenv check --schema https://example.com/schema.json

# This is rejected
zenv check --schema http://example.com/schema.json
# Error: HTTP URLs are not supported for security reasons. Use HTTPS.

Private Repositories: For private GitHub repos, you may need to:

• Use a personal access token in the URL (not recommended for shared environments)
• Set up a private schema server with authentication
• Use a local copy in CI with secrets management

Full Changelog

v0.3.3 (2026-01-17)

Added:

• Remote schema support via HTTPS URLs
• Automatic schema caching with 1-hour TTL
• --no-cache flag for all schema-accepting commands
• Remote URL support in extends field
• Relative URL resolution for remote extends

Security:

• HTTPS-only enforcement for remote schemas
• HTTP URLs rejected with clear error message

v0.3.2 (2026-01-16)

Added:

• Secret detection with --detect-secrets flag
• zenv diff command for comparing .env files
• Detection patterns for AWS, Stripe, GitHub, GitLab, Slack tokens
• High-entropy string detection for potential secrets

Changed:

• Improved error messages for validation failures
• Better handling of multiline values in diff output

Installation

First-Time Install

Via cargo (recommended):

cargo install zorath-env

Or download the binary for your platform from GitHub Releases:

• Linux: zenv-linux
• macOS Intel: zenv-macos-intel
• macOS Apple Silicon: zenv-macos-arm
• Windows: zenv.exe

Upgrade

If you already have zenv installed:

cargo install zorath-env --force

Verify Installation

zenv version
# zenv v0.3.3

Check for updates anytime:

zenv version --check-update

Resources

• Documentation: zorl.cloud/zenv
• Full Docs: zorl.cloud/zenv/docs
• GitHub: github.com/zorl-engine/zorath-env
• Wiki: GitHub Wiki
• Package: crates.io/crates/zorath-env
• Community: r/zorath_env

---

Ready to share schemas across your team? Run cargo install zorath-env or download the latest binary from GitHub Releases.