Skip to content

janet-brand defs

Declarative definitions for the janet-brand institutional runtime.

Defs are authored in YAML (or JSON for item lists) and loaded through load_brand_object_any_file. They provide the data layer that brand runtimes, region simulations, game sessions, and biologic systems consume.

Canonical apiVersion

All new def files should use:

apiVersion: net.plantange/v1

Legacy plantange.net/v1 values have been normalized to net.plantange/v1. STATUS.md tracks any future regressions.

Category overview

Category Format State
games/ YAML (flat declarative simulation) canonical
quest/ YAML (multi-doc) migrating
regions/ YAML mixed — one migrating, rest legacy
biologic/ YAML / JSON reference
vegetation/ YAML reference
vehicle/ YAML reference
items/ JSON reference
producers/ TOML legacy

See each category's README.md for format contract and authoring guidance.

Schema ref conventions

To keep schema refs predictable across tools and CI, use this convention:

  • Keep $id as the canonical hosted URL under https://internal.plantange.net/schemas/....
  • Use relative $ref for in-repo cross-schema links (for example ../../meta/v1/meta.json).
  • Do not mix hostnames or ad-hoc URI roots inside $id/$ref values.

This repository intentionally uses canonical IDs for publication and relative refs for local maintainability.

Local validation standard

When validating locally with check-jsonschema, always pass --base-uri to force local reference resolution (instead of fetching through canonical $id URLs):

check-jsonschema \
    --base-uri "file:///ABS/PATH/TO/schemas/world/v1/spec.json" \
    --schemafile schemas/world/v1/spec.json \
    schemas/world/v1/examples/starter_world.yml

Repeat the same pattern for other schema roots by changing the schema path.

Standard command for this repository:

sh scripts/validate-world-layout-schema.sh

This script is the same command used in GitLab CI.

Lifecycle states

State Meaning
canonical Executable, formally structured, serves as reference implementation
migrating Has proper frontmatter; actively being brought to canonical shape
reference Well-structured data; not yet wired to runtime validation
legacy Authored in obsolete format; needs conversion before use

See STATUS.md for per-file inventory.