Skip to content

Schema Discovery

This document defines the project-wide convention for loading schema files.

Overview

Schema loading uses a 3-tier fallback strategy.

  1. Remote URL fetch via PLANTANGENET_SCHEMA_BASE_URL
  2. Local directory override via PLANTANGENET_SCHEMA_DIR
  3. Sibling checkout fallback at ../../plantangenet-core/schemas

This matches the behavior implemented in keyframe load_schema_document and schema_fixture_path.

Environment Variables

PLANTANGENET_SCHEMA_BASE_URL

Base URL used for remote schema fetch.

Default:

https://gitlab.internal.plantange.net/plantangenet/core/-/raw/main/schemas

Resolved file format:

{PLANTANGENET_SCHEMA_BASE_URL}/{relative_path}

Example:

world/v1/spec.json -> https://gitlab.internal.plantange.net/plantangenet/core/-/raw/main/schemas/world/v1/spec.json

Use this variable when:

  • CI should pull schemas from a mirror
  • You need a branch-specific or pinned schema host
  • You run a local HTTP mirror for integration testing

PLANTANGENET_SCHEMA_DIR

Absolute path to a local schemas directory, typically a checkout of:

/home/srussell/src/plantangenet-core/schemas

When set, local fixture resolution prefers this path and fails fast with a clear error if the directory does not exist.

Use this variable when:

  • Running in offline or air-gapped environments
  • Working without access to the GitLab instance
  • Forcing deterministic local schema fixtures during tests

Development

No configuration is required if both repositories are checked out side-by-side. The sibling fallback resolves automatically.

Optional explicit override:

export PLANTANGENET_SCHEMA_DIR=/home/srussell/src/plantangenet-core/schemas

CI (online)

Use the default base URL, or set:

PLANTANGENET_SCHEMA_BASE_URL=https://gitlab.internal.plantange.net/plantangenet/core/-/raw/main/schemas

CI (offline / restricted network)

Mount a schema directory and set:

PLANTANGENET_SCHEMA_DIR=/path/to/plantangenet-core/schemas

Production

Prefer URL-first behavior so runtime environments do not require local schema checkouts. Use PLANTANGENET_SCHEMA_BASE_URL for host pinning.

Troubleshooting

  • Error: failed to load schema from URL, PLANTANGENET_SCHEMA_DIR, or sibling checkout
  • Verify relative schema path
  • Verify network reachability to the base URL
  • Verify sibling checkout exists

  • Set PLANTANGENET_SCHEMA_DIR explicitly

  • Error: PLANTANGENET_SCHEMA_DIR points to path that does not exist

  • Correct the path or unset the variable
  • docs/PROVISIONING.md
  • web/docs/runtime/world-spec-api.md
  • keyframe/src/lib.rs