struct_to_gts_schema: honor user-supplied #[derive(JsonSchema)] so schemars field helpers (length/email/extend) become usable

[diffora]

Problem

#[gts_type_schema] / struct_to_gts_schema injects #[derive(schemars::JsonSchema)] from inside the attribute-macro expansion. That has two downstream effects that together make it impossible to attach standard schemars validation helpers — #[schemars(length(min = 1, max = 255))], #[schemars(email)], #[schemars(extend(\"format\" = \"uuid\"))] — to struct fields.

1. Helper-attribute ordering: legacy_derive_helpers deny

#[schemars(...)] is a derive helper attribute: the parser only recognises it as legal once a corresponding #[derive(JsonSchema)] has been registered on the same item. Because gts_type_schema injects the derive at expansion time, at first parse the helpers look orphaned and rustc fires the legacy_derive_helpers lint (deny-by-default in 2024 edition). The user cannot use any schemars helper on a GTS struct's fields.

2. Workaround "add the derive manually" doesn't work — duplicate impl

The obvious workaround is to put #[derive(schemars::JsonSchema)] on the struct yourself, above #[gts_type_schema(...)]. gts-macros already contains a has_derive check (src/lib.rs:351) and add_missing_derives filters by it (src/lib.rs:481-513), so in principle this should suppress the auto-injection. In practice on 0.9.3 we still get duplicate impl JsonSchema for X → error[E0119]: conflicting implementations of trait.

Reproducer (boiled down from account-management-sdk::gts::UserV1):

```rust
use modkit_gts::gts_type_schema; // wraps gts_macros::struct_to_gts_schema

#[derive(schemars::JsonSchema)] // try to claim the derive up-front
#[gts_type_schema(
dir_path = "schemas",
schema_id = "gts.cf.core.am.user.v1~",
description = "...",
properties = "id,username",
base = true,
)]
pub struct UserV1 {
pub id: gts::GtsInstanceId,
#[schemars(length(min = 1, max = 255))]
pub username: String,
}
```

Observed: E0119 on JsonSchema for UserV1. Expected (per the in-code comment on has_derive): macro detects the user derive and skips its own.

Why it matters

Real-world contract drift: hand-authored JSON Schemas in docs/schemas/ declare minLength, maxLength, format: email on string fields. The Rust-generated mirror via #[gts_type_schema] produces a schema without those constraints, so runtime validators accept any non-empty string for length-constrained fields and any string for email-formatted fields. Same shape will repeat for every future GTS base envelope that wants to express even basic field constraints. This is tracked in our codebase as TODO(am-user-schema-constraints).

Proposal

Two parts, in priority order:

1. Fix the has_derive suppression so a user-supplied #[derive(schemars::JsonSchema)] (and likewise Serialize/Deserialize for base structs) reliably prevents the macro's own injection. May require either (a) examining attrs after derive expansion, or (b) reordering so the macro's add_missing_derives runs against the attrs it actually emits.
2. Once (1) is in place, helper attrs work for users who opt into the manual-derive form. Optionally, document the pattern in the README and the #[gts_type_schema] rustdoc, with an example showing #[schemars(length(...))] / #[schemars(email)].

A more invasive alternative for (2) — out of scope for a first cut: re-emit user-supplied #[schemars(...)] field attrs into the macro output so the lint never fires, regardless of derive placement. But fixing (1) is enough to unblock real users.

Version

Observed on gts-macros = \"0.9.3\". Related (same crate): #85 (x-gts-traits-schema support).

[aviator5]

Took a look — the good news is this already works on current main (PR #92), with no change to has_derive needed. The diagnosis in the issue is mostly off; let me break it down.

(Naming note: in this repo the macro is gts_macros::struct_to_gts_schema — I'll use that below. modkit_gts::gts_type_schema is your downstream wrapper around it; since it's also an attribute macro, everything here applies to it identically.)

The E0119 you hit is purely attribute ordering, not a has_derive bug. An attribute macro never receives the attributes listed above it — those apply to the macro's output. So when you put #[derive(schemars::JsonSchema)] above the attribute, the macro literally cannot see it, doesn't suppress its own injection, and you get two impl JsonSchema → conflict. That also means proposal 1(a) ("examine attrs after derive expansion") is impossible — the macro can't observe attributes it was never handed.

You don't need a manual derive at all. Standard schemars field helpers ride straight through:

#[struct_to_gts_schema(/* base = true, ... */)]
pub struct UserV1 {
    pub id: gts::GtsInstanceId,
    #[schemars(length(min = 1, max = 255))]
    pub username: String,
}

The macro auto-injects #[derive(JsonSchema)] at struct level (above the fields), so legacy_derive_helpers never fires, and because the emitted GTS document is built from schemars::schema_for!, the constraints land verbatim in the schema (minLength/maxLength, format, the extend keyword, etc.). No contract drift.

If you do want an explicit #[derive(schemars::JsonSchema)] (e.g. for Serialize/Deserialize on a base struct too), it works — just place it below the attribute, where the macro can see it and skip its own injection.

Live demo (regenerated golden test, PR #92): gts-macros/tests/golden/traits_referenced_chain.rs — PriorityTraitV1 carries #[schemars(length(min = 1, max = 32))] on a string field plus a derived Priority enum, and both surface in the committed golden schema (minLength/maxLength + enum: ["low","medium","high"]).

One real caveat: a named nested type (like the Priority enum) is factored into $defs and $ref'd by schemars, and the macro only inlines its own known defs (GtsInstanceId/GtsTypeId) — so the $ref would dangle. Add #[schemars(inline)] on that type (container-level) and it's embedded in place. Field helpers and inlined types need nothing special; carrying arbitrary user $defs through the macro would be a separate enhancement.

Net: part 2 of the proposal already works; part 1 (fixing has_derive) is unnecessary. The remaining gap is documentation — worth a short rustdoc/README note: "schemars field helpers work directly; a manual JsonSchema derive must go below the attribute; inline nested named types." Happy to do that doc pass.

[diffora]

Confirmed — @aviator5 is right, and I've now verified it end-to-end on gts-macros = 0.10.0 + schemars = 1.2 in our downstream tree. The original diagnosis in this issue was off; no has_derive change is needed.

Root cause was attribute ordering, exactly as described. The E0119 we hit came from placing #[derive(schemars::JsonSchema)] above #[gts_type_schema(...)], where an attribute macro can't see it (those attrs apply to the macro's output), so it injected its own derive → duplicate impl. Reading the 0.10.0 source confirms the mechanism:

• the GTS document is built from schemars::schema_for!(Self), so #[schemars(...)] field helpers land verbatim;
• add_missing_derives pushes #[derive(JsonSchema)] onto the struct's own attrs (struct level), so legacy_derive_helpers never fires and no manual derive is required.

What we did (the account-management UserV1 envelope that motivated this): just added field helpers, no manual derive:

#[gts_type_schema(/* base = true, type_id = "gts.cf.core.am.user.v1~", ... */)]
pub struct UserV1 {
    pub id: gts::GtsInstanceId,
    #[schemars(length(min = 1, max = 255))]
    pub username: String,
    #[schemars(extend("format" = "email"))]
    pub email: Option<String>,
    #[schemars(length(min = 1, max = 255))]
    pub display_name: Option<String>,
    // first_name / last_name likewise
}

minLength/maxLength/format now appear in the generated schema verbatim and are enforced by our fail-closed runtime validator — contract drift gone, regression-guarded by a unit test on the generated schema. Two notes for anyone landing here:

• #[schemars(length(...))] works on Option<String> too — schemars models it as {"type": ["string","null"], "minLength": …, "maxLength": …} and the bounds ride through.
• For the email format we used the #[schemars(extend("format" = "email"))] form (it's what we already use elsewhere and it lands "format": "email" exactly); we didn't separately exercise the #[schemars(email)] shorthand.

So part 2 already works; part 1 (has_derive) is unnecessary, agreed. The only remaining gap is documentation — +1 to your doc-pass offer (rustdoc/README note: "schemars field helpers work directly; a manual JsonSchema derive must go below the attribute; inline nested named types with #[schemars(inline)]"). Happy to have this closed once that lands, or close as resolved.