Skip to content

Field-level deprecated metadata is dropped for referenced schemas #1574

Description

@ayush22667

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:

"deprecated": true,

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions