This repository was archived by the owner on May 13, 2026. It is now read-only.
feat(schema): unblock fold_db_node openapi.rs registration ( path-prefix + FieldBase inline) - #683
Merged
Conversation
…istration Phase 4 follow-on to slice 3 (#681) and slice 3-extension (#682). The slice-3 family registration in fold_db_node hit four classes of utoipa \$ref resolution issues post-cascade: 1. utoipa renders fully-qualified type paths with dots ("crate::schema::types::field_value_type::FieldValueType" → "crate.schema.types.field_value_type.FieldValueType") which don't match the registered component names. Fixed via module-scope `use` statements in: - access/types.rs: super::capability::{CapabilityConstraint,CapabilityKind} - schema/types/declarative_schemas.rs: FieldAccessPolicy + FieldValueType - schema/types/field/base.rs: atom::{Molecule,MoleculeHash,MoleculeRange,MoleculeHashRange} so the bare type names appear in field declarations / alias macros. 2. utoipa's #[aliases(...)] on FieldBase<M> registers aliases as separate components but does NOT substitute alias names into bare `FieldBase` references in dependents (SingleField/HashField/etc. via #[serde(flatten)]). Fixed by adding #[schema(inline)] to each variant's `base` field so the FieldBase shape is inlined directly into the variant schema rather than \$ref'd. 3. SchemaWithState's `pub schema: Schema` field referenced the `pub use ... as Schema` alias. utoipa emits \$ref: Schema (alias name), but the canonical component is named DeclarativeSchemaDefinition. Fixed by changing the field type to DeclarativeSchemaDefinition directly (drop the alias usage in this load-bearing wire shape). 4. (no functional change) Inline-FieldBase refactor avoided — chose the smaller `#[schema(inline)]` annotation approach instead, which keeps FieldBase<M>'s impl methods intact while making the OpenAPI spec resolve cleanly. Verified locally: cargo fmt + clippy -D warnings + workspace tests (662 core tests + observability all green, no regressions). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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
Phase 4 follow-on to slice 3 (#681) and slice 3-extension (#682). The slice-3 family registration in fold_db_node hit four classes of utoipa $ref resolution issues post-cascade:
1. $ref path-prefix quirks
utoipa renders fully-qualified type paths with dots:
```
"crate::schema::types::field_value_type::FieldValueType"
→ "crate.schema.types.field_value_type.FieldValueType"
```
which don't match the registered component names. Fixed via module-scope `use` statements in:
so the bare type names appear in field declarations / alias macros.
2. `#[aliases]` doesn't substitute into bare `FieldBase` references
utoipa's `#[aliases(...)]` on `FieldBase` registers aliases (`FieldBaseSingle`, `FieldBaseHash`, etc.) as separate components but does NOT substitute alias names into bare `FieldBase` references in dependents (`SingleField`/`HashField`/etc. via `#[serde(flatten)]`).
Fixed by adding `#[schema(inline)]` to each variant's `base` field so the FieldBase shape is inlined directly into the variant schema rather than $ref'd. Avoids the larger inline-FieldBase refactor that would have required moving 60+ `.base.X` accessors across the field/ module and `variant.rs`.
3. `SchemaWithState.schema` referenced the `Schema` alias
`SchemaWithState` had `pub schema: Schema` where `Schema` is a `pub use crate::schema::types::declarative_schemas::DeclarativeSchemaDefinition as Schema;` re-export. utoipa emits `$ref: Schema` (alias name), but the canonical component is named `DeclarativeSchemaDefinition`.
Fixed by changing the field type to `DeclarativeSchemaDefinition` directly. Drops the alias usage in this load-bearing wire shape.
Why
Without these fixes, fold_db_node's Phase 4d' regen produces 14 unresolved $refs even though all the underlying types have ToSchema. After this lands + the bump cascade, fold_db_node's openapi.rs registration resolves cleanly with zero unresolved $refs.
Parent: gbrain `projects/api-typegen-unification`. Recipe: gbrain `projects/register-schema-field-bodies`.
Test plan
🤖 Generated with Claude Code