libLogit

Config Schema Audit

This page is the public schema-status companion to the contract docs. It compares the current schema files to the Beta contract direction and explains what is already aligned, what remains transitional, and what still needs a true Beta schema freeze.

Schema Files In The Repo Today

File	Purpose
schema/logit.v1.schema.json	Versioned v0.1 global-config contract.
schema/logit.v2.schema.json	Current named-`LOGIT` registry schema.
schema/logit.schema.json	Legacy/general schema alias retained in the repo.

Audit Summary

The repo already has a meaningful v2 schema. The main Beta problem is not “there is no schema.” The real problem is that the schema still carries both portable contract fields and several migration/compatibility aliases at the same time.

That means the current state is:

strong enough for Alpha and ongoing Beta work
useful for config validation today
not yet the final simplified Beta schema vocabulary

What The Current v2 Schema Already Gets Right

Area	Current state
Named registries	Supported through `defaults` plus `logits`.
Version marker	`version: "0.2"` is defined.
Level vocabulary	Current public levels are enumerated.
Path-mode vocabulary	`file` and `directory` are enumerated.
Sink vocabulary	`console`, `file`, `network`, and `database` are enumerated.
JSON versus text	`format` currently validates `text` and `json`.
Rotation object	Present with `maxBytes` and `maxFiles` variants.
Retention object	Present with record, age, and byte-style controls.
Redaction object	Present for Python reference behavior.
Buffering object	Present for Python reference behavior.
Failure policy object	Present for Python reference behavior.
Unknown-key rejection	`additionalProperties: false` is used aggressively, which is good for catching drift.

Where The Schema Is Still Transitional

1. Canonical fields and aliases coexist

The v2 schema currently accepts both canonical and compatibility names such as:

localPath and local_path
outputDirectory and output_directory
pathMode and path_mode
remotePath and remote_path
databasePath and database_path
failurePolicy and failure_policy

This is practical for migration, but it means the schema is still serving two purposes at once:

validate the Beta direction
keep old or mixed styles loading

2. Legacy migration names still exist in v2

The v2 schema still accepts older field names like:

file_location
network_file_location
database_location

That is helpful for Alpha compatibility, but Beta still needs a clearer answer to “which names should new docs teach by default?”

3. Advanced Python-first fields live beside baseline cross-language fields

The schema includes:

redaction
buffering
failurePolicy
database-specific retention controls

Those are real and valuable, but they are not yet portable across all bindings. So the schema currently models both:

portable baseline behavior
Python-reference advanced behavior

That is acceptable for now, but the Beta freeze needs clearer status rules for what is required versus binding-specific.

v1 To v2 Comparison

Concern	v0.1 schema	v0.2 schema	Audit note
Global versus named loggers	Single global config	Named registry with defaults	v2 is clearly the long-term direction.
File output field	`file_location`	`path`, `localPath`, aliases	v2 is more flexible but still more permissive than final Beta likely should be.
Remote output field	`network_file_location`	`remotePath`, aliases	Alpha remote-path baseline is represented.
Database store	none	`databasePath` and retention fields	v2 carries Python reference retained-store behavior.
Advanced runtime controls	none	buffering, failure policy, redaction	Useful, but not yet universal.

Contract Alignment Snapshot

Aligned already

These areas are already in good shape relative to the public contract:

named LOGIT registries
level vocabulary
path-mode vocabulary
sink vocabulary
local path, remote path, and output-directory concepts
rotation and retention object presence
explicit unknown-key rejection

Partially aligned

These areas are real, but still need Beta cleanup:

canonical-versus-alias precedence in docs and examples
portability expectations for advanced runtime fields
schema naming for the eventual Beta-frozen version
final answer on which aliases remain accepted indefinitely

Not yet finished

These areas still need dedicated Beta decisions:

whether to publish a logit.beta.schema.json successor or evolve logit.v2.schema.json
whether some migration aliases should move from first-class support to documented compatibility-only handling
how to represent unsupported optional fields consistently across non-Python bindings

Practical Guidance For Developers Today

If you are writing new config today, prefer:

localPath
outputDirectory
pathMode
remotePath
databasePath
level
sinks
format
metadata
rotation
retention

Treat these as compatibility or migration names rather than primary teaching vocabulary:

local_path
output_directory
path_mode
remote_path
database_path
file_location
network_file_location
database_location

Beta Freeze Work Still To Do

The remaining schema-hardening work is pretty concrete:

choose the final Beta schema versioning story
publish the canonical vocabulary more aggressively than the aliases
classify every advanced field as required, optional, or binding-specific
keep migration aliases working without letting them dominate new examples
decide how strict the final supported-binding contract must be about fields not yet implemented everywhere

Why This Still Counts As Progress

Even before the final schema freeze, the current state is already useful:

config files can be validated
migration from v0.1 has a documented path
current examples are grounded in a real schema
the repo has enough structure to keep evolving toward a tighter Beta contract

The goal of this audit is not to pretend the schema freeze is done. The goal is to make the current state legible so Beta work can proceed without guesswork.