AttributeDefinition.returned is required by the JSON deserializer despite RFC 7643 defining it as optional

[johnstone3]

Describe the bug

AttributeDefinition fails to deserialize a SCIM /Schemas response when an attribute
definition omits the returned characteristic. RFC 7643 §7 explicitly documents returned
as having a default value ("default. ... DEFAULT."), which in practice across the SCIM
ecosystem means service providers may omit it and expect the default to apply. The SDK
instead treats it as a required JSON creator property and throws.

Environment

• scim2-sdk-client / scim2-sdk-common: reproduced on 3.2.0, 4.0.0, 4.1.0, 4.1.1, 5.0.0, 5.1.0
  and 6.0.0 (latest) — not fixed by any release in this range.
• Reproduced against a real-world server: Keycloak's SCIM preview feature (26.6+), whose
  /Schemas response omits returned on attributes that use the default value (e.g. the
  complex name attribute on the core User schema).

To Reproduce

Minimal /Schemas fragment missing returned on one attribute:

{
  "name": "name",
  "type": "complex",
  "multiValued": false,
  "required": false,
  "caseExact": true,
  "mutability": "readWrite",
  "uniqueness": "none",
  "subAttributes": [ ... ]
}

Calling scimService.getSchemas() (or any path that deserializes SchemaResource) against
a server returning this shape throws:

com.fasterxml.jackson.databind.exc.MismatchedInputException: Missing required creator property 'returned' (index 9)
 (through reference chain: com.unboundid.scim2.common.types.SchemaResource["attributes"]
   ->java.util.ArrayList[12]->com.unboundid.scim2.common.types.AttributeDefinition["returned"])
	at com.unboundid.scim2.client.requests.SearchRequestBuilder.invoke(SearchRequestBuilder.java)
	at com.unboundid.scim2.client.ScimService.getSchemas(ScimService.java)

Expected behavior

Since RFC 7643 documents a default value for returned ("default"), the SDK should apply
that default when the field is absent from the JSON, consistent with how uniqueness
(default "none") is already handled as optional in the current AttributeDefinition
constructor.

Root cause

In AttributeDefinition's @JsonCreator constructor:

@NotNull @JsonProperty(value = "mutability",  required = true)
final Mutability mutability,
@NotNull @JsonProperty(value = "returned", required = true)
final Returned returned,
@Nullable @JsonProperty(value = "uniqueness")
final Uniqueness uniqueness,

Both mutability and returned are marked required = true, despite RFC 7643 §7
documenting default values for both ("readWrite" and "default" respectively). Only
uniqueness (default "none") and caseExact are optional in the same constructor.

This report reproduces the returned case specifically, against a real server that omits
it. The identical pattern applies to mutability — a server that omits it to rely on the
documented default would hit the same MismatchedInputException — though I have not
reproduced that case against a live server, so I'm flagging it as a related suspicion
rather than a confirmed second bug.

Suggested fix

Drop required = true from the returned (and likely mutability) parameter and default
to Returned.DEFAULT (Mutability.READ_WRITE) when absent, matching the RFC 7643 §7
semantics — the same way uniqueness already defaults when omitted.

[kqarryzada]

The AI summary on this is a bit verbose, but it seems that the main point is that returned should be treated as Returned.DEFAULT when it is omitted. At first glance, this seems like a good behavior to employ. RFC 7643 Section 2.2 does suggest that this is appropriate.

Before we can commit to this, I'll need to investigate and make sure that there are not any serious backward compatibility concerns as a result of this change.