libLogit

Beta Schema Version Strategy

This page defines how libLogit should move from the current Alpha v0.2 config schema to a Beta-frozen schema story.

Current State

The repo currently ships:

• schema/logit.v1.schema.json for the legacy global config shape
• schema/logit.v2.schema.json for the named-LOGIT registry shape

That is enough to support Alpha and ongoing Beta work, but it does not yet settle the final question:

should Beta freeze the existing v2 shape as-is, or introduce a more explicit Beta-labeled successor?

Decision Goals

The Beta schema version strategy should optimize for:

1. a stable public config contract
2. a sane migration path from v0.1 and current Alpha v0.2 usage
3. a clear canonical field vocabulary
4. enough flexibility to keep compatibility aliases during transition without letting them dominate the long-term product

Recommended Direction

The current best direction is:

Keep v0.1 versioned for compatibility

• schema/logit.v1.schema.json remains the documented legacy shape
• migration from v0.1 continues to load as one default LOGIT

Treat the current v0.2 schema as the working Beta baseline

• schema/logit.v2.schema.json remains the active working schema
• public docs should increasingly teach canonical names inside that shape
• compatibility aliases should remain documented as transitional, not primary

Publish an explicit Beta successor only if the freeze requires breaking cleanup

If Beta freeze work reveals that the final supported schema must materially change, use one of these approaches:

1. schema/logit.beta.schema.json
2. schema/logit.v3.schema.json

The repo should not introduce a new schema file only for aesthetics. A new schema version should earn its existence by representing a real contract change.

Canonical Vocabulary To Freeze

Regardless of the final filename, Beta should increasingly teach:

• localPath
• outputDirectory
• pathMode
• remotePath
• databasePath
• level
• sinks
• format
• metadata
• rotation
• retention

These should be treated as compatibility or migration names rather than the main public vocabulary:

• local_path
• output_directory
• path_mode
• remote_path
• database_path
• file_location
• network_file_location
• database_location

Compatibility Rules During The Freeze

Until the final Beta schema is declared:

• existing Alpha-compatible aliases may continue to validate
• new examples should prefer canonical names
• new public docs should explain aliases as compatibility paths, not the main product story
• unsupported advanced fields must not be silently treated as portable

Decision Triggers For A New Schema Version

Create a new Beta schema file only if one or more of these become true:

1. canonical names must become exclusive for supported-Beta configs
2. advanced fields must be reclassified in a way that changes validation
3. migration aliases need to move from accepted fields to compatibility-only translation logic
4. the registry/defaults layout itself changes

If none of those happen, the better move is likely to keep improving and documenting logit.v2.schema.json rather than minting a new file.

Beta Freeze Deliverables

The schema freeze is not complete until all of these are true:

• one public schema story is chosen
• the schema choice is documented in release notes
• canonical fields are obvious in the main docs
• migration from v0.1 is still documented
• the conformance and config examples all point at the same vocabulary

Related Sources

• Config schema audit
• Configuration guide
• Migration guide
• Burndown