docs: model-layer codegen design specifications#138
Draft
OmarAlJarrah wants to merge 1 commit into
Draft
Conversation
Add a docs/codegen/ directory of design specifications for the planned model-layer code generator. These are design documents only — no generator or generated code is added to the repository. - json-field-model.md: a dependency-free four-state JSON field wrapper (JsonField<T>: Known / Missing / Null / Raw) plus an embedded RawJson tree, with all Jackson conversion kept behind the Serde SPI in the adapter, mirroring how Tristate is split. Documents the read-path (forward-compat) vs PATCH-path (three-state) boundary so JsonField and Tristate are never wrongly merged. - model-classes.md: generated models as a field map plus one-line typed accessors over a hand-written runtime that owns the invariant machinery, with an explicit coverage (module-scoped Kover exclusion) and binary-compatibility (separate .api baseline) strategy for generated code. - model-validation.md: an opt-in, memoized, fail-soft validate()/isValid()/ validity() triad that is never run on the deserialize path and serves as the fallback union-disambiguation strategy behind discriminator matching. - discriminator-const-fields.md: const and discriminator fields generated as defaulted raw values with dual (typed + raw) accessors. Add a docs/codegen/README.md index and link it from the repository README documentation table.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
docs/codegen/directory of design specifications for the planned model-layer code generator. These are design documents only — no generator code, no KotlinPoet templates, and no generated sources are added. Every Kotlin/Java snippet is clearly labeled as illustrative target output showing the shape a future generator would emit, grounded in the realsdk-coreAPI (Tristate, theSerdeSPI,Paginator,RequestBody, and theTristateModuleadapter pattern).The unifying principle, matching how
sdk-coreis already built: logic lives in a hand-written runtime, generated code stays thin.What's included
json-field-model.md— the foundation. A dependency-free four-state field wrapperJsonField<T>(Known/Missing/Null/Raw) plus an embeddedRawJsontree, with all Jackson conversion kept behind theSerdeSPI in the adapter, mirroring howTristateis split today. Documents the read-path (forward-compat) vs PATCH-path (three-state) boundary soJsonFieldandTristateare never wrongly merged.model-classes.md— generated models as a field map plus one-line typed accessors over a hand-writtenJsonModelruntime that carries the invariant machinery. Includes an explicit coverage strategy (module-scoped Kover exclusion from the aggregate floor) and binary-compatibility strategy (a separate.apibaseline for generated code).model-validation.md— an opt-in, memoized, fail-softvalidate()/isValid()/validity()triad that is never invoked on the deserialize path, used only as the fallback union-disambiguation strategy behind discriminator matching.discriminator-const-fields.md— const and discriminator fields generated as defaulted raw values with dual (typed + raw) accessors.A
docs/codegen/README.mdindex ties the specs together and is linked from the repository README documentation table.Notes
The four-state field model is the foundation the other three specs build on; the dependency order is captured in the index.
apiDump/ build steps are out of scope here since this PR adds only Markdown.Closes #51
Closes #64
Closes #65