ToSchema derives array with items with allOf combination of the types of all the tuple elements

[taladar]

Given e.g.

use utoipa::{OpenApi, ToSchema};

#[derive(ToSchema)]
struct A((Option<String>, String));

#[derive(OpenApi)]
#[openapi(components(schemas(A)))]
struct Api;

fn main() {
    println!("{}", Api::openapi().to_pretty_json().unwrap())
}

we get

{
  "openapi": "3.0.3",
  "info": {
    "title": "utoipa-test",
    "description": "",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "paths": {},
  "components": {
    "schemas": {
      "A": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "type": "string",
              "nullable": true
            },
            {
              "type": "string"
            }
          ]
        }
      }
    }
  }
}

which seems to be the schema for a type that fulfills all the requirements at the same time instead of one where each element fulfills one of the requirements.

This happens for both enum and struct fields and it does not seem to matter if the field is named which leads me to conclude that the location of the tuple within the type we derive ToSchema on probably doesn't matter.

[taladar]

Tuples don't seem to be supported exactly in OpenAPI but it would probably be possible to at least use anyOf and minItems and maxItems to get as close as OpenAPI allows the validation to go.

Alternatively if someone uses a tuple and it is not supported by utoipa at all it should probably lead to a compile error.

[emersion]

It should be possible to set minItems/maxItems to constrain the size of the array, then use prefixItems to describe each entry.

[juhaku]

According to how serde serializes tuples https://serde.rs/json.html see the struct X it will serialize to array of 2 fields. Thus the generated schema is also generated accordingly.

[taladar]

But this schema requires every element of the tuple to satisfy the types of all of them which obviously won't work.

[juhaku]

@taladar Ah, true, instead it should serialize as anyOf. I'll try to check this out and fix it soon.

[emersion]

anyOf wouldn't faithfully represent the tuple constraints. My suggestion above would.

[juhaku]

True, the limitation should already be present on some tuples though. It should actually set that the array should contain 2 items. But it does not set prefix items though. But it might be that it does not take account all cases. Nonetheless while those min_items and max_items are provided they are only for visual validation and does not really prevent users of providing more or less items if the endpoint was executed e.g. with curl.

utoipa/utoipa-gen/src/component/schema.rs

Lines 607 to 610 in 576f6c1

	.to_array_builder()
	.max_items(Some(#fields_len))
	.min_items(Some(#fields_len))
	#description

[taladar]

Technically speaking the entire schema does not prevent any client from sending any random data to the endpoint.

[juhaku]

Yeah, it just shows "what a good guy should send"

[juhaku]

@emersion That is true,

I'll change the tuple implementation out of the allOf thingly. That was a relic from past in the OpenAPI 3.0 which did not conform fully to JSON Schema spec. Since OpenAPI 3.1 it is fully conforming the JSON Schema we can use the prefixItems defined here: https://json-schema.org/understanding-json-schema/reference/array#tupleValidation. This allows full tuple support for OpenAPI as well as stated by @emersion.

[emersion]

Thank you so much!