Type Array in Schema object

[dickermoshe]

Throws an error when trying to parse type that has a list. This is very uncommon.

Here Adult has a property nullableChildren that could be interpreted as List<String?> However, this is such an uncommon bug that I would consider it a feature request. Maybe a better error message though, freezed doesn't do that well :(

  type 'List<dynamic>' is not a subtype of type 'String?' in type cast
  package:openapi_spec/src/open_api/index.g.dart 934:27         _$$SchemaObjectImplFromJson
  package:openapi_spec/src/open_api/index.freezed.dart 8812:7   new _$SchemaObjectImpl.fromJson
  package:openapi_spec/src/open_api/index.freezed.dart 8530:28  _$SchemaFromJson

Schema

``` components: schemas: Adult: allOf: - $ref: '#/components/schemas/Person' - properties: children: items: $ref: '#/components/schemas/Child' type: array nullableChildren: items: $ref: '#/components/schemas/Child' type: - array - 'null' - string nullableChildrenVariant2: oneOf: - type: 'null' - items: $ref: '#/components/schemas/Child' type: array type: object description: A representation of an adult Child: allOf: - properties: age: format: int32 type: integer type: object - $ref: '#/components/schemas/Person' description: A representation of a child Nullable.Address: description: A representation of an address whose value can be null. nullable: true properties: city: type: string street: type: string type: object Person: discriminator: mapping: a: '#/components/schemas/Adult' c: Child propertyName: $_type properties: $_type: type: string address: properties: city: type: string street: type: string type: object firstName: type: string lastName: type: string maidenName: maxLength: 255 type: - string - 'null' nullableSkills: items: properties: name: type: string type: object type: - array - 'null' nullableSkillsVariant2: oneOf: - type: 'null' - items: properties: name: type: string type: object type: array secondHomeAddress: $ref: '#/components/schemas/Nullable.Address' skills: items: properties: name: type: string type: object type: array type: object info: license: name: MIT title: Example version: 1.0.0 openapi: 3.1.0 paths: /person/display/{personId}: get: operationId: list parameters: - description: The id of the person to retrieve in: path name: personId required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Person' description: OK servers: - url: http://api.example.xyz/v1 ```

[IcarusSosie]

This issue actually won't stay uncommon for long as more organizations and tools start using OAS v3.1.

I'm currently running into this specific issue as well, and after looking at the code, it seems the reason is because the latest OAS version supported by this package is OAS v3.0.3, according to their respective specifications.

I found a migration guide that outlines the breaking change that causes this specific issue : https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0

Here's the relevant excerpt from the article :

Swap nullable for type arrays

In line with JSON Schema, the type keyword can now define multiple types for a schema with an array. This is useful new functionality, but has also made nullable redundant. In order to achieve the goal of letting JSON Schema tools understand OpenAPI, it was decided to remove nullable entirely instead of deprecate it.

# OpenAPI v3.0
type: string
nullable: true

# OpenAPI v3.1
type:
- "string"
- "null" 

This follows the keyword independence concept, where keywords should only add constraints, but adding one more keyword should not remove a constraint. Find and replace should solve this one rather quickly.

So, in compliance with OAS v3.1, the nullable property should be removed, and the type property should now be a List of enum values, but it currently is a nullable string. Furthermore, the string is used as a discriminator in a freezed union, which makes this fix non-trivial, since it seems to require reconsidering the possible structures of the SchemaObject class.

The article also outlines the fact that schema declarations can now specify the JSON-Schema version to use (via $schema) when parsing it, which would, in theory, allow for backwards compatibility, and have both 3.0.3 and 3.1 schemas in the same API spec. This means the fix should allow for both behaviors to coexist.

In my opinion, this issue should be renamed "Support OAS v3.1".