Multiple issues with current specification

[clementdenis]

In current (2024.08.3) specification, we found multiple issues, some when upgrading to latest Java SDK (v19+), others while running the specification though the OpenAPI validator

I'll report all of them in a single issue, but let me know if you prefer me to open separate issues.

The main issues are covered by individual commits on a branch from our fork of the Java SDK: clementdenis/okta-sdk-java@master...clementdenis:okta-sdk-java:fix-openapi-spec

since and until params in /api/v1/logs have incorrect format

This issue makes the generated clients have a String instead of the proper date-time object (Instant in Java).
The fix is just to set the right format (this is a regression, it was OK in previous versions).

Can't update scope on AppUser

The current spec makes it impossible to update the scope of an existing AppUser.

It was previously possible to do this, as POST /api/v1/apps/{appId}/users/{userId} used to take an AppUser as request body (which includes the scope field).
More generally, the latest versions of the specification have more specific request body definitions, which would seem like a good thing but actually makes the SDKs harder to use, because request and responses for the same REST endpoint are not interchangeable anymore (as this issue demonstrates for the Java SDK). I don't know how this should be fixed, but I would be OK with less specific definitions if it makes the SDKs easier to use.

The fix adds a AppUserScopeRequestPayload variant to AppUserUpdateRequest.

Invalid schema for elements field in UISchemaObject

It is supposed to be an array of UIElement (correct in the examples though), but is specified as a simple UIElement.
Fix here.

allOf used with a single $ref pointing to an array type

I don't know if this is supposed to be valid OpenAPI (does not cause validation error), but it makes sense that you can't "mix" arrays and objects (allOf being necessarily an object). Anyway, this generates empty model classes on Java and other generated SDKs, making the affected methods unusable.

The fix is to "inline" the allOf to a simpel $ref.
Note that we might not have identified all the occurrences of this issue, as they're not obvious.

Incorrect definition of UserSchemaAttribute.enum

Just an indent issue, that break the generated field.

Other validation-only issues

The commits are explicit about their issue, they don't cause any functional problem in the generated SDK like the previous ones.

OpenAPI: Fix type used with $ref
OpenAPI: Remove invalid default value for date-time field
OpenAPI: Remove unused models with invalid array definitions
OpenAPI: Minor validation issues

[clementdenis]

We found an additional issue: some enums are declared using the wrong case. For example, KnowledgeConstraint.MethodEnum/TypesEnum are mapped in uppercase, while the API actually returns lowercase values (but accepts both upper and lower case ...).

We fixed that temporarily in the Java SDK by activating case-insensitive deserialization of enum values, but it would be better to actually fix the case of enums in the specification.