New Feature Proposal: Complex Attributes and Embedded Objects

[Tony Tkacik]

Dear ConnId community,

at Evolveum, we identified a need to support complex attributes (embedded objects) to provide full support for SCIM 2.0 and other REST-based APIs.

We propose the following additions to ConnId to achieve support for complex attributes:

1. Introduce the concept of Embedded Objects and their support as attribute values to represent complex attributes

2. Introduce a new delta operation which supports nested complex deltas to manipulate complex attributes / embedded objects.

3. Allow non-String UID values

We at Evolveum are very interested in these features, and would like to develop it, if it makes sense to you. What do you think?

Below you can find more detailed proposal for these additions.

1. Introduce Embedded Objects Classes / Complex Attribute Values

EmbeddedObject is a new type of valid attribute value, which can be used to represent complex attributes in a ConnectorObject.

Its schema is described by ObjectClassInfo similar to other objects, but with a flag embedded.

EmbeddedObject does not require UID and Name attributes, but can contain other attributes as defined by the ObjectClassInfo.

Rationale: The simple attributes in ConnId are not sufficient to cover modern REST APIs and SCIM 2.0 endpoints and currently require additional mapping
and value transformations inside the connector implementations to flatten structure, instead of providing data as-is.
This also prevents full dynamic support of custom SCIM 2.0 resources (which may contain custom structured attributes) without the need to modify SCIM 2.0 connector.

Design and Implementation

Introduction of a new class EmbeddedObject, which extends BaseObject, but not ConnectorObject. This also allows for better distinctions between operations working on normal objects and embedded objects and does not impose UID and Name requirements on embedded objects.

• Enable EmbeddedObject as a valid value for Attribute.

• Update ObjectClassInfo and ObjectClassInfoBuilder not to require UID and Name attributes for embedded object classes.

• Implement serialization and deserialization of EmbeddedObject

This is sufficient for read-only support of embedded objects and basic update capabilities when the entire embedded object is added/replaced/deleted.

2. Delta Operation support for embedded object classes

The addition of the ComplexUpdateDeltaOp operation provides support for more granular updates of the attributes and values in the embedded objects.

Rationale: With the introduction of embedded objects, it is necessary to provide a way to modify attribute of these objects without having to replace the entire parent object.
SCIM 2.0 and other protocols may support executing similar types of deltas natively, so this would allow for more efficient updates.

Design and Implementation

Addition of new API & SPI operation ComplexUpdateDeltaOp, which would allow for the specification of a delta operation on an attribute or embedded objects.

• Currently UpdateDeltaOp should be unchanged in order to preserve backwards compatibility.

• Delta will be represented as a tree structure, allowing for more representing more complex modifications.

  • Allows to represent more complex nested operations

  • Provides natural grouping of related changes

• the ComplexUpdateDeltaOp would have a method public Set<BaseAttributeDelta> updateDelta(ObjectClass objclass, Uid uid, Set<BaseAttributeDelta> modifications, OperationOptions options);

  • ComplexUpdateDeltaOp capabilities are superset of UpdateDeltaOp, since it supports updating both simple and complex attributes.

• interface BaseAttributeDelta - new common interface which will be implemented by existing AttributeDelta and new ComplexAttributeDelta in order to allow reuse of existing support for simple attributes.

• ComplexAttributeDelta - a new class representing modifications to a complex attribute or embedded object

  • contains name of attribute

  • list of ValueDelta objects representing modifications to the values of the attribute

• ComplexValueDelta - a new class representing modifications to an embedded object. Contains the following information

  • selector/filter to identify the value to be modified

    • Initially, this could be limited to AndFilter and EqualFilter combinations

  • Operation type

    • ADD - add new value

    • DELETE - remove values identified by selector/filter

    • MERGE - apply nested deltas to matched value

      • contains a list of BaseAttributeDelta representing nested modifications to the attributes of embedded object.

    • There is no need to have a special REPLACE type, since replace is a combination of DELETE(ALL) + ADD(o1)

3. Allow non-String UID values

The UID attribute of a ConnectorObject should not be limited to String values, but should allow for any value type.

Rationale: SQL databases and other systems frequently use non-string values as unique identifiers, such as integers.
The current requirement requires connectors to convert these values to/from String, which is not always desirable or efficient, and introduces additional mapping complexity.

Example: Team object class with UID attribute of type Integer (as in Forgejo / Gitea / Codeberg)

Design and Implementation

The UID attribute of a ConnectorObject should be changed to allow any value type, not just String.

• Property getUidValue should be deprecated, since not all UID values are String anymore, but it will continue to return a String representation of the UID value for backwards compatibility.

As mentioned earlier, we at Evolveum are very interested in these features and would like to develop them if it makes sense to you. What do you think?

Thanks for your feedback.

---
Anton Tkáčik
Backend Technical Leader and Developer
evolveum.com

[Francesco Chicchiriccò]

Hi again Tony,
complex values are something we could feel the need of, indeed. so I am +1 for the described changes below.

See also my note on new major version in the reply for proposals to enable low-code connectors.

Regards.

--
You received this message because you are subscribed to the Google Groups "connid-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to connid-dev+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/connid-dev/1591404327.2312952.1753268324695.JavaMail.zimbra%40evolveum.com.

-- 
Francesco Chicchiriccò

Tirasa - Open Source Excellence
http://www.tirasa.net/

Member at The Apache Software Foundation
Syncope, Cocoon, Olingo, CXF, OpenJPA
https://about.me/ilgrosso

[Tony Tkacik]

Hi again,
so what should be the next steps for developing this functionality?

1. Create improvements for features in the ConnId base Jira
2. Create and prototype functionality

3. Create pull requests

Regards,

Tony

---

From: "Francesco Chicchiriccò" <ilgr...@apache.org>
To: "connid-dev" <conni...@googlegroups.com>
Sent: Monday, August 4, 2025 11:13:03 AM
Subject: [Spam]  Re: [connid-dev] New Feature Proposal: Complex Attributes and Embedded Objects

To view this discussion visit https://groups.google.com/d/msgid/connid-dev/eb64e190-ffe9-4c39-9a38-32a57943afcf%40apache.org.