Error: Unknown type: TupleType

[ericcarino]

Tuples appear to not be supported. Is this correct or a bug?

export interface ClusterStats {
    ...
    prop1: Array<[string, Array<any>]>;
    prop2: Array<[string, Array<any>]>;
}

Error produced when trying to build swagger doc.

There was a problem resolving type of 'ClusterStats'.
Generate swagger error.
 Error: Unknown type: TupleType
    at new GenerateMetadataError (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/exceptions.js:17:28)
    at resolveType (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:56:15)
    at resolveType (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:69:30)
    at /Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:496:23
    at Array.map (<anonymous>)
    at getModelProperties (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:462:14)
    at getReferenceType (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:281:26)
    at resolveType (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:95:25)
    at Object.resolveType (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/resolveType.js:73:20)
    at MethodGenerator.Generate (/Users/ecarino/go/src/github.com/nefeli/pangolin/dashboard/rest/node_modules/tsoa/dist/metadataGeneration/methodGenerator.js:30:34)

[endor]

You're right. Tuple doesn't seem to be supported yet. At least I can't find a reference to it in resolveType. Any interest in adding it?

[endor]

I'll close this for now. Let me know if you have any other questions.

[HoldYourWaffle]

@endor I'm not sure why this was closed, the feature hasn't been added yet.
I have created a very basic implementation, once it's done I'll submit a PR.
Right now it still lacks proper tests and schema/spec generation (I only need very basic parsing myself) but I think I'll have the time to add these things somewhere in the coming weeks.

[dgreene1]

@WoH made a great point:

A quick thing to note: Even OAPI3 has no way to enforce the order of types as far as I know

So I’m not sure that we should support heterogenous/mixed-type tuples until OpenAPI supports heterogenous tuples. Here’s the issue thread that explains why OpenAPI can’t properly support heterogenous tuples:

OAI/OpenAPI-Specification#1026

I will say that we could support homogeneous tuples like [string, string]. I realize that this has limited utility, but I don’t think that tsoa should offer any functionality that OpenAPI doesn’t offer. I say this because it would be inconsiderate if tsoa allowed an API to be documented so that a user thinks they can submit [number, string] when only [string, number] is allowed. And since OpenAPI can’t document the order of the tuple, then tsoa wouldn’t be able to clarify the scenario.

[WoH]

@dgreene1 can we reopen this given for discussion maybe?

@WoH I think it was be discourteous to API consumers to allow them to submit [“aString”, 4] when only [4, “aString”] is allowed. And since the order of mixed types can not be communicated via Swagger/OpenAPI3, I really don’t want to be on the hook for a miscommunication of that magnitude. I stated this in the issue for this PR, but I would only approve a PR that generated documentation for a homogeneously-types tuple since order doesn’t matter in that circumstance.

I have to slightly disagree here. I agree it's not perfect to have slight inconsistencies here. I'd definitely want a description that communicates the order.

However, not implementing this is not a better solution. It basically forces the API developer to accept anything (just like we would have to do) and check on their own, when a tuple could've been specified instead. At the end of the day, either tsoa or the developer will have to tell the api user that the order was not as expected (which can't be deduced from the spec alone in both cases.

[HoldYourWaffle]

So I’m not sure that we should support heterogenous/mixed-type tuples until OpenAPI supports heterogenous tuples.

Do you mean "not support" as in error or just a warning? I don't think it's fair to error route generation just because a completely different feature doesn't support it. There's no additional processing required for heterogeneous tuples so as far as I can tell here, here and here would be the appropriate places for a check and potential warning/error, so non-swagger users are not affected.

[dgreene1]

I have to slightly disagree here. I agree it's not perfect to have slight inconsistencies here.

As I mentioned, I think that we should update the design goals of tsoa to clarify that we should not provide runtime validation that can not be communicated via Swagger/OpenAPI.

I'd definitely want a description that communicates the order.

That description could become available if OAI/OpenAPI-Specification#1026 ratified/implemented. However, until that day we would be miscommunicating to the users.

Currently the best we could do is:

type: array
items:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
minItems: 2
maxItems: 2

And that ^ has the (in my opinion) large issue of not clarifying the order.

I feel like we would be encouraging users to use a type that is really ineffective at communicating to consumers what they need to send. And isn't communicating to consumers the whole point of having a Swagger/OpenAPI document?

The only compromise I see would be to warn in all cases if a tuple is used:

• If the specVersion is 2, then we warn "tuples are not allowed in Swagger 2. please change your specVersion config to 3"
• If the specVersion is 3 and if the tuple has mixed types (i.e. ["myString", 3]) then we warn that:

console.warn(`the generated swagger output is not capable of communicating the order of the tuple. Until the OpenAPI specification officially mixed-type supports tuples, please consider using a "named tuple approach" as follows:

interface INamedTuple {
  myFirstKey: string
  mySecondKey: number
}

interface IObjectThatHasATuple {
  theTuple: Array<INamedTuple>
}
`);

If this compromise is acceptable, then I'm more open to dropping my proposed design goal (i.e. "that we shouldn't have runtime validations that OpenAPI can't document") for this particular case.

I will re-open the issue if someone is interested in creating a PR that meets that acceptance criteria (and has unit tests that verify via test spies that the warnings are being written).

[HoldYourWaffle]

If the specVersion is 2, then we warn "tuples are not allowed in Swagger 2. please change your specVersion config to 3"

I assume you only want this for heterogeneous tuples? Based on this comment I don't see a reason why homogeneous tuples wouldn't be possible in swagger 2.

If the specVersion is 3 and if the tuple has mixed types (i.e. ["myString", 3]) then we warn that:

That warning looks good to me.

I will re-open the issue if someone is interested in creating a PR that meets that acceptance criteria (and has unit tests that verify via test spies that the warnings are being written).

I'll probably be able to do it once I know how to generate the swagger/open api part.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days

[HoldYourWaffle]

#451 (comment)

[fantapop]

It looks like support for Tuples in openapi 3 will land in 3.1.0:

https://stackoverflow.com/questions/57464633/how-to-define-a-json-array-with-concrete-item-definition-for-every-index-i-e-a#answer-5746519

I see that RC0 was tagged in June. https://www.openapis.org/blog/2020/06/18/openapi-3-1-0-rc0-its-here Hopefully its coming soon!

[aktary]

This is still a problem in v5.1.1.

export type TChatRequest = { question: string; history: [string, string][]; };

causes:

There was a problem resolving type of 'TChatRequest'.
GenerateMetadataError: Unknown type: TupleType