Description
Field-level deprecated and example metadata is omitted when a field's schema
is represented by a $ref. The same metadata is generated correctly for a
primitive field.
This is reproducible with utoipa 5.5.0.
Minimal reproduction
use utoipa::{OpenApi, ToSchema};
#[derive(ToSchema)]
enum CountryAlpha2 {
US,
IN,
}
#[derive(ToSchema)]
struct PaymentRequest {
/// Deprecated: use `profile_id` instead.
#[schema(deprecated, example = "US")]
business_country: Option<CountryAlpha2>,
/// Deprecated: use `profile_id` instead.
#[schema(deprecated, example = "legacy")]
business_label: Option<String>,
}
#[derive(OpenApi)]
#[openapi(components(schemas(CountryAlpha2, PaymentRequest)))]
struct ApiDoc;
fn main() {
let openapi = ApiDoc::openapi();
let output =
serde_json::to_string_pretty(&openapi).expect("OpenAPI serialization should succeed");
println!("{output}");
}
Dependencies:
[dependencies]
serde_json = "1"
utoipa = "5.5.0"
Actual generated schema
{
"business_country": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CountryAlpha2",
"description": "Deprecated: use `profile_id` instead."
}
]
},
"business_label": {
"type": [
"string",
"null"
],
"description": "Deprecated: use `profile_id` instead.",
"deprecated": true,
"example": "legacy"
}
}
The referenced business_country field keeps its description, but loses:
The primitive business_label field retains both attributes.
The same deprecation omission occurs for a required referenced field, where the
property is emitted directly as a $ref.
Expected behavior
Field-level metadata should be preserved when the field references another
schema. For example:
"business_country": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CountryAlpha2"
}
],
"description": "Deprecated: use `profile_id` instead.",
"deprecated": true,
"example": "US"
}
Additional context
This appears related to the composite-schema limitation discussed in #1394,
where OneOfBuilder does not support deprecation metadata. However, this report
is specifically about metadata silently being dropped from a field whose type
is a referenced schema.
The behavior was also observed with utoipa 4.2.3, where optional references
are represented using nullable allOf.
Description
Field-level
deprecatedandexamplemetadata is omitted when a field's schemais represented by a
$ref. The same metadata is generated correctly for aprimitive field.
This is reproducible with
utoipa 5.5.0.Minimal reproduction
Dependencies:
Actual generated schema
{ "business_country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryAlpha2", "description": "Deprecated: use `profile_id` instead." } ] }, "business_label": { "type": [ "string", "null" ], "description": "Deprecated: use `profile_id` instead.", "deprecated": true, "example": "legacy" } }The referenced
business_countryfield keeps its description, but loses:The primitive
business_labelfield retains both attributes.The same deprecation omission occurs for a required referenced field, where the
property is emitted directly as a
$ref.Expected behavior
Field-level metadata should be preserved when the field references another
schema. For example:
Additional context
This appears related to the composite-schema limitation discussed in #1394,
where
OneOfBuilderdoes not support deprecation metadata. However, this reportis specifically about metadata silently being dropped from a field whose type
is a referenced schema.
The behavior was also observed with
utoipa 4.2.3, where optional referencesare represented using nullable
allOf.