Association Definitions with custom Association Types

[jri]

When defining a composite type it should be user configurable which association type to be used at instance-level for representing the parent-child relationship.

Currently the instance-level association type is fixed and is determined by the association definition type used:

Type-level Association Type	Instance-level Association Type
Composition Definition	Composition
Aggregation Definition	Aggregation

The parent-child semantic is preserved. Consequently the role types are still fixed (Parent, Child). They are not user configurable.

Model

To each Association Definition an additional Association Type is assigned -- the Instance-level Association Type. Every association type, regardless of simple or composite, is applicable -- also user defined ones. The assignment is optional. If no Instance-level Association Type is assigned the standard one is used (see above).

Webclient GUI

For composite topics the detail panel shows -- for each child topic -- also the (simple or composite) values of the association leading to that child. So, in the API jargon the detail panel renders hierarchies of Related Topics (instead of hierarchies of Topics). A Related Topic is a topic-association pair. This applies to both, the detail panel's info rendering and the form rendering.

Association fields can be excluded from rendering by the means of the (association type's) View Configuration's hidden and locked settings. (Analogous to the topic type's view configurations.)

Protocol

In an update request the childs property does not contain sole topics, but Related Topics. That is the request does not only update the topic values but also the association values (of the Relating Associations in the API jargon).

The same could apply to create requests.
(See also #647)

[JuergeN]

As I am not sure if this is covering my needs completely, I feel like writing a bit more:

As a user I want to be able to create new (custom) composition types and aggregation types and give them a meaning (like with the existing custom association types). I think this is needed to be able to use DM fully semantical.

Examples:

To specify a private address and a work address, for the very moment it is necessary to add "labels" (another TopicType?) in between the relations. But in the sense of semantic modelling I want to modell them like this:

Address[1]---is WORK ADDRESS of--->Person[1]
Address[2]---is PRIVATE ADDRESS of--->Person[1]

which equals (instance in details panel):

  Maria Mustermann
  ...

  * Address (TopicType)

    - Foobarstr. 123, 456789 City, Country
      (WORK ADDRESS)    <--custom aggregation type

    - Barfoostr. 321, 456789 City, Country
      (PRIVATE ADDRESS) <--custom aggregation type

Same is true for custom composition types of course ...

This feature is urgently needed, so that people can model their composites in the right way asap.

[jri]

No, this would NOT be supported by the type model proposed in this ticket.

The current concept is: attach an Association Definition with the information which Association Type to be used at instance-level. That is one instance-level association type per association definition. What would be the one instance-level association type in your example? You use 2.

You could have one association type Address Entry with subtypes Work Address and Private Address. But in DM4 we deliberately do NOT support inheritance. So there are no subtypes.

Instead you could model your case as follows: use Address Entry as the instance-level association type, and have Address Label as a Child Type of Address Entry. Address Labels's could be home, work ... or just undefined as well. So, that's basically the Address model utilized at the moment but without the Address Entry topic in between (currently Address Entry is a topic type, not an association type).

[JuergeN]

ok - I think this is just a bit of confusion. I was not thinking about inheritance. I think we are on the same track. Let's try to sirt this out. I want to be able to create a custom association definition including the name (label) of the association type and to dertermine which Association Type to be used at instance level, where Association Type can be

1. Aggregation
2. Composition
3. Association (directional or undirectional)

I want to use it on both levels, in the type builder and on instance level. I think it is exactly what yu are saying:

use Address Entry as the instance-level association type, and have Address Label as a Child
Type of Address Entry. Address Labels's could be home, work ... or just undefined as well. So,
that's basically the Address model utilized at the moment but without the Address Entry topic
in between (currently Address Entry is a topic type, not an association type).

Let me try to give you another example: I want to add a birthday to every PersonType?, by defining a custom aggregation definition "Birthday" between PersonType? and a DateType?:
So in the Type Level it would look like this:

PersonType?(parent)-----custom AggregationDefinion? named Birthday----->DateType?(child)

On the instance level (map) it should look like this:

Peter-----Birthday(aggregation)-----13.03.1973

In the details panel (edit mode) it could look like this:

---------------
|Peter Miller |
---------------
...

Birthday [Date]
------------------
|v| 13.03.1973|
------------------

On instance level I could also use the Birthday aggregation as a custom association to make a connection between two other existing topics on the map.

Are we on the same track?

[jri]

When you wrote this instance-level example:

Address[1]---is WORK ADDRESS of--->Person[1]
Address[2]---is PRIVATE ADDRESS of--->Person[1]

do you mean one association definition is underlying here (then we're not on the same track), or do you mean two association definitions are underlying here (we're on the same track then).

Rendering of the Detail Panel is a different thing.
I don't understand the details (resp. your underlying rules) of your Birthday example.

• You talk about a named Aggregation Definition, but Aggregration Definitions are not named.
• Do you mean that in the map rendering each "Birthday" association should be rendered with the label "Birthday". According to what rule might this happen then?
• The Detail Panel would not render "Birtday" as the field header, but "Date" (the topic type). According to what rule "Birthday" (an association type) could be rendered here?

So, I understand intuitively what you want accomplish but to me it looks rather like an ad-hoc example without underlying rules.

Do you like to call me? This get too complicated here.

[JuergeN]

Replying to jri:

When you wrote this instance-level example:

Address[1]---is WORK ADDRESS of--->Person[1]
Address[2]---is PRIVATE ADDRESS of--->Person[1]

do you mean one association definition is underlying here (then we're not on the same track), or do you mean two association definitions are underlying here (we're on the same track then).

Two! :)

Rendering of the Detail Panel is a different thing.
I don't understand the details (resp. your underlying rules) of your Birthday example.

• You talk about a named Aggregation Definition, but Aggregration Definitions are not named.
• Do you mean that in the map rendering each "Birthday" association should be rendered with the label "Birthday". According to what rule might this happen then?
• The Detail Panel would not render "Birtday" as the field header, but "Date" (the topic type). According to what rule "Birthday" (an association type) could be rendered here?

So, I understand intuitively what you want accomplish but to me it looks rather like an ad-hoc example without underlying rules.

Do you like to call me? This get too complicated here.

Yes, I will call you ...

[jri]

Replying to JuergeN:

Two! :)

Yeah, OK. I understand your idea then.

However, having one Association Definition for each "label" (that is "home", "work", ...) makes modeling cumbersome in case another label should be added. A complete Association Definition must be created, along with Assoc Type, Cardinality, ... settings. That is much more labor than needed, and a source for errors.

With my suggestion -- define "Address Entry" as a composite Association Type, with "Address Label" as a simple child topic type -- things become easy and natural: a new address label, e.g. "holiday", can be introduced just by creating another "Address Label" instance.

[JuergeN]

So here is what we want to do after we talked:

1. The user shall create a new AssociationType?

2. As AssociationTypes? can also be a composite, for modelling the Address Entry example above (jri's suggestion), the user would do the following:

a) create new Association Type "Address Entry" of data type 'composite'
b) create new Topic Type "Address Label" of data type 'text'
c) associate the two objects with an Aggregation Definition, where "Address Entry" is the parent type and "Address Label" is the child type.

3. The GUI must provide the possibility to asign an arbitrary association type to an association definition (Aggregation Definition or Composition Definition).

PS: Most of this is already there: I have just created a new AssociationType? "Address Entry" as a composite and modelled it the way I described above. It works just as it should. So on instance level one can already create custom associations where you can then choose the pre-defined values from your composition definition. WOW! That's DeepaMehta! :)

[jri]

Development on this feature starts now.
We need it also in conjunction with #696.

[jri]

Replying to jri:

We need it also in conjunction with #696.

This has not proved true, see ticket:696#comment:2

Anyways, development of this feature (see ticket description) starts NOW.

[Jörg Richter <jri@…>]

In d00a4808e14cc092395fb8fe934a0f1bd9337fb9/deepamehta:

Core: fix JSON (#341).

See #341.

[Jörg Richter <jri@…>]

In f186ca6ff2043f0e1205bda5fbf1a306e9e0306b/deepamehta:

Core migr no.4: add inst-level-assoc-type (#341).

Core migration no.4 adds "Association Type" as a child to Composition Definition and Aggregation Definition.

In the Webclient you can set the Instance level association type for a comp def and aggr def.
IMPORTANT: at the moment you must choose an assoc type. Otherwise the DB will be corrupted.

You can test the feature by checking out branch inst-level-assoc-type.

See #341.

[Jörg Richter <jri@…>]

In 3816628376016157e10c35853f2f9f56c25c26de/deepamehta:

Core: custom assoc types are functional (#341).

The feature Custom Association Types (formerly: Instance-Level Association Types) is basically functional.

Try this:

1. Create a topic type "Book".
2. Create an association type "Author".
3. Reveal the topic type "Person" and create an Aggregation Definition between Book and Person. Choose "Author" as the custom association type.
4. Create a Book instance. Type in an Autor (Person). Press OK.
5. Reveal the book's author (via detail panel). You see the book is connected with the person via an association of type Author.

A lot of issues remain.

BREAKING CHANGES

Core API:

• 1 additional parameter in the all-args AssociationDefinitionModel constructor:

  AssociationDefinitionModel(long id, String uri, String typeUri, String customAssocTypeUri,
      String parentTypeUri, String childTypeUri,
      String parentCardinalityUri, String childCardinalityUri,
      ViewConfigurationModel viewConfigModel)
  

  New is the 4th parameter: customAssocTypeUri. The URI of the custom association type.

If null is passed no custom association type will be set.

• Changed semantics of a AssociationDefinitionModel getter method:

  String getInstanceLevelAssocTypeUri()
  

  Returns the custom association type if set. Otherwise returns the default association type (which depends on the association definition's type).

• The JSON representation of an association definition contains an additional property: custom_assoc_type_uri. The URI of the custom association type. If not set the value is null. Works in both directions: serialization (when send over wire), and parsing (e.g. in a declarative migration).

See #341.

[Jörg Richter <jri@…>]

In dc0a5356ed6a1e20104b9e1ee94034b462189581/deepamehta:

Core: delete child topics (#341).

When a topic/association whose type definition includes custom association types is deleted those child topics which have "Composition" semantics are deleted as well.

See #341.

[Jörg Richter <jri@…>]

In 0dc005de8b5e37e7d943d5f2a926e0919ca55267/deepamehta:

Webclient: use assoc type as field label (#341).

When a custom association type is set and the child type is simple the detail panel renders the name of the custom association type as field label (instead the name of the child type).

Example: child type is "Date" (simple) and custom association type is "Birthday". The date field is labeled "Birthday" then.

Committed to the inst-level-assoc-type branch.

See #341.

[Jörg Richter <jri@…>]

In 1814a1b8c7cc3a11413fd6f16548d29d4dd0e43b/deepamehta:

Fix: Custom assoc type is up-to-date (#341).

See #341.

[JuergeN]

Hi Jörg, I just recently started with testing this feature. In the very recent version of 4.6 nightly (Demo Server - logged in as admin ) it seems the feature is not yet available when editing the assoc dev in the webclient. Is this on purpose?

[jri]

You could test the feature when building from branch inst-level-assoc-type (instead of master). I'm hesitant to merge it as long as it is not ready for release as this would make releasing a possible 4.5.1 (without that feature) much more cumbersome. But when we decide not to release a 4.5.1 we could do the merge now.

Your testing is appreciated very much!

[JuergeN]

I do not want to interfere with your release plannings at this point. There might be good reasons for a soonish 4.5.1 release. Just let me know about your schedule and ping me when it's time to get back to this.

[Jörg Richter <jri@…>]

In 0e6f409926adff09c06fe7fe07f962a2e021613a/deepamehta:

Core: optimize child topic loading (#341).

DeepaMehtaObject's loadChildTopics() method loads only those child topic-trees which are not loaded already.

See #341.

[Jörg Richter <jri@…>]

In cf3e5aafa807ba05bd14a652420313ae0ac78fd0/deepamehta:

Display custom assoc values in page panel (#341).

The values of an custom association (instance) are displayed in the detail panel in case the custom association type is composite. Applies to both, info rendering, and form rendering (however the form input is not yet processed).

Try this:

1. Create an Association Type "Address Entry", make it "Composite", and associate the (existing) Topic Type "Address Label" as a child type, via Aggregation Definition.
2. Delete the Association Definition between Topic Type "Person" and Topic Type "Address Entry".
3. Associate Topic Type "Address" as a child type to Topic Type "Person", via Composition Definition (or Aggregation Definition if you like). As the Custom Association Type choose "Address Entry".
4. When now editing a Person, its Address topic will be directly connected to the Person topic, via an association of type "Address Entry". The Address Label topic ("home", "work") is connected to that association. When revealing the Address Entry association in the map it is labeled with "home" or "work".

Conclusion: The intermediate Address Entry topic is gone. It is replaced by a custom association.

You can test it by building the inst-level-assoc-type branch.

CHANGES

1 method changed in Webclient (additional 3rd parameter):

dm4c.fetch_topic(topic_id, include_childs, include_assoc_childs)

1 method changed in RESTClient (additional 3rd parameter):

dm4c.restc.get_topic_by_id(topic_id, include_childs, include_assoc_childs)

See #341.

[Jörg Richter <jri@…>]

In 98899314f65a1611c951218ea7506e435cc4131e/deepamehta:

Type Editor: edit custom assoc types (#341).

In the Type Editor (when selecting a composite type topic and then pressing Edit): the association definition's Custom Association Types are displayed and can be changed via a Combobox.

CHANGES

Core API

2 new methods in AssociationDefinition interface:

String getCustomAssocTypeUri()
void setCustomAssocTypeUri(String customAssocTypeUri)

The getter returns the custom association type, or null if not set.

1 new method in AssociationDefinitionModel class:

String getCustomAssocTypeUri()

Returns the custom association type, or null if not set.

RenderHelper?

1 new method:

dm4c.render.topic_combobox(topic_type_uri, item_value_prop, selected_id_or_uri)

Renders a combobox whose menu is populated by all topics of the specified type.
Similar to topic_menu().

BREAKING CHANGES

GUIToolkit

1 method replaced in class Combobox with changed semantics:

select_by_label(item_label)     # obsolete
->
select(item_value)

Combobox selection is by value (not by label). Analogous to class Menu.
If no menu item with this value exists an exception is thrown.
Unless the value is null or undefined; in that case the Combobox's input field is cleared.

See #341.

[Jörg Richter <jri@…>]

In 392b9ed5209130ad29ba653255e43bffada994b3/deepamehta:

Type Editor fix: remove custom assoc types (#341).

In the Type Editor (when selecting a composite type topic and then pressing Edit): the Custom Association Type assigned to a association definition can be removed by emptying the Combobox's input field.

CHANGES

Core API

1 new method in ChildTopics interface:

ChildTopics remove(String childTypeUri, String topicUri)

Removes a child topic by-URI.

See #341.

[Jörg Richter <jri@…>]

In e34f297db416d67e8c491c000f9b903bf590467e/deepamehta:

Store custom association values (#341).

Values of Custom Associations entered in the detail panel are stored.

The scenario is: a composite topic whose type includes association definitions with a Custom Association Type set is edited in the detail panel. The Custom Association Type is composite as well (otherwise its fields would not be rendered at all).

Note: this particular combination is not yet supported: Aggregation Definition with a simple child type.

See #341.

[Jörg Richter <jri@…>]

In d2e9123f2e27d1158932be6298ef75e2079da0c5/deepamehta:

Core: fix fetching custom association type (#341).

See #341.

[Jörg Richter <jri@…>]

In d3ac17993f7265d0d4438d00063560c6dc00453e/deepamehta:

Fix multi fields with custom assoc types (#341).

See #341.

[Jörg Richter <jri@…>]

In 65e6472bddc40a9435d76a23522d3c2137b0cd7a/deepamehta:

Webclient: refactor page model (#341).

See #341.

[Jörg Richter <jri@…>]

In 91aa1abb0a0646aec83f2a595f3da57a08314b5e/deepamehta:

Fix remove buttons for multi fields (#341).

See #341.

[Jörg Richter <jri@…>]

In c484ba2c20ae4891fa441df6b0c3a7781b024317/deepamehta:

Webclient: refactor page model pt.2 (#341).

See #341.

[JuergeN]

Just a funny observation: When one edits the color code in the view config of an association type that is included in a custom association definition, the result on instance level varies. Especially after changing the color again, the results seam coincidental. (Observed on nightly build today.)

[jri]

Replying to JuergeN:

Just a funny observation: When one edits the color code in the view config of an association type that is included in a custom association definition, the result on instance level varies. Especially after changing the color again, the results seam coincidental. (Observed on nightly build today.)

The color value you input must be a valid CSS color, that is e.g. #cc00cc. The # is mandatory here. I saw this was missing. This should solve the problem.

[Jörg Richter <jri@…>]

In 948f92305dc2abed49bdd7c2c1324278ce3cd6a8/deepamehta:

Field label is "Custom Association Type" (#341).

When editing an association definition the field to set the custom association type is properly labeled "Custom Association Type" instead of "Association Type" which was ambigous as such a field exists in the same form already. Furthermore this is consistent with the labeling used in the Type Editor (when selecting a type and pressing Edit).

Note: this field label is generated from the association definition meta-model. Remember that in the detail panel a field of a simple child topic is labeled with the name of the custom association type (instead of with the name of the child type), if one is involved. The custom association type is now associated to an association definition via an association of type "Custom Association Type" (instead of "Aggregation"). The association type "Custom Association Type" itself is the custom association type of the association definitions that attaches the meta-type "Association Type" as a child to the association types "Composition Definition" and "Aggregationn Definition" in order to define the concept of a Custom Association Type in the first place. That means that the meta-model is defined partly by itself. Phew... that was fun ;-)

CHANGES

Core API

1 new AssociationDefinitionModel convenience constructor that takes a Custom Association Type URI (but no ID, URI, or view config):

AssociationDefinitionModel(String assocTypeUri, String customAssocTypeUri,
                           String parentTypeUri, String childTypeUri,
                           String parentCardinalityUri, String childCardinalityUri)

See #341.

[Jörg Richter <jri@…>]

In 1b06442f6d25115da6a2b76ffc55826d6a5c3933/deepamehta:

Fix: remove troublesome migration from repo (#341)

The build works again.

See #341.

[Jörg Richter <jri@…>]

In c77952711167cc7e05a1775a37d884b01cf0d7b4/deepamehta:

Fix tests (#341).

See #341.

[Jörg Richter <jri@…>]

In cca172614a3c59b2bb8126404bc1c932e8a2352a/deepamehta:

Contacts module: fix JSON (#341).

See #341.

[Jörg Richter <jri@…>]

In bf8eb4a835f68a22aecaeaac48df7d69ddb9ea67/deepamehta:

Contacts model: prepare for redefinition (#341).

See #341.

[Jörg Richter <jri@…>]

In e4c808f262282ec27c708f2002e0f0ef4a701f84/deepamehta:

Webclient: revert assoc type label rule (#341).

The name of a Custom Association Type is no longer used as a field label in the detail panel.

Commit [0dc005de] is reverted. See discussion in ticket:779#comment:3

This brakes the "Birthday" example scenario but at least works well with the Contacts model that is delivered with the DM Standard Distribution.

See #341.

[Jörg Richter <jri@…>]

In e5aa2d2ea376e4682f80860be9dcc8b4bda97286/deepamehta:

Webclient: fix form processing (#341).

E.g. creating a Person and leaving the Phone field empty works again.

Note: when the Phone field is empty no empty Phone topic will be created (resp. if the field is emptied the Phone topic will be deleted), see #171. That means that there is no Phone Entry association either in this case. As a consequence no Phone Label ("home", "work", ...) can be stored. There can be no Phone Label without a Phone number.

This is a generic pattern. Form input bound to a custom association is ignored/deleted if the child topic is not created resp. deleted.

See #341.

[Jörg Richter <jri@…>]

In 4471404c47dc6fb343086fd8039b35c6a8e884aa/deepamehta:

Core: fix view config update (#341).

See #341.

[Jörg Richter <jri@…>]

In d0e7f1b18aef428e9438f7a2072079091fbce810/deepamehta:

Core: fix label config storage (#341).

A cold start (no DB exists) works again.
It was broken some days ago.

See #341.

[Jörg Richter <jri@…>]

In a854980087827d6e0a573d17b65bacedfee8910a/deepamehta:

Webclient: custom assoc type label rule (#341).

The detail panel renders the name of the custom association type as the child topic's field label (instead of the child type's name) if all conditions are met:

1. the child type is simple
2. a custom association type is set
3. the custom association type is simple

New is the 3rd condition.

This rule is considered generally applicable and to work well with all kinds of application models.
At least it works reasonable with these example models:

• Child type is "Phone" (simple) and custom association type is "Phone Entry" (composite). -> The Phone field is labeled "Phone" then.

• Child type is "Date" (simple) and custom association type is "Birthday" (simple). -> The Date field is labeled "Birthday" then.

• Child type is "Association Type" (a meta type, technically simple) and custom association type is "Custom Association Type" (simple). -> The Association Type field is labeled "Custom Association Type" then.

The latter example shows part of DM's meta model definition. Click an association definition instance to see the effect in the detail panel.

Thank you, JuergeN, for comming up with this label rule!

See #341.
See #779.

[Jörg Richter <jri@…>]

In 25dbd77f2c74f85c8a2e38f92daf59e87e679181/deepamehta:

Core fix: topic refs including assoc info (#341).

JuergeN's "Person-Company" example now works. That adds a simple "Company" child type to the "Person" type via Aggregation Definition and sets "Organizational Role" as the Custom Association Type. "Organizational Role" is a composite association type having "Role Label" as its child type, again via Aggregation Definition. "Role Label" is a simple type (of data type "Text").

CHANGES

REST API:

In an update request when referencing an existing topic (via ref_id: or ref_uri: prefix) you can update the Relating Association as well. That is useful in conjunction with custom associations.

Formerly a reference was just a string (e.g. "ref_id:2345"), so there was no opportunity to specify any values for the association (the Relating Association) that connects the referenced topic:

{
    id: 1234,
    childs: {
        child.type.uri: "ref_id:2345"
    }
}

Now you can wrap a reference in a topic object, and add values for the Relating Association by using the topic's "assoc" property. Put the actual reference in the topic's "value" property.

{
    id: 1234,
    childs: {
        child.type.uri: {       <-- topic
            value: "ref_id:2345",
            assoc: {            <-- relating association
                value: ...
                childs: ...
            }
        }
    }
}

Note: the former format remains supported. It is handy when no custom associations are involved.

Core API:

To support topic references which hold info about the relating association as well, TopicReferenceModel is derived from RelatedTopicModel (instead of TopicModel) since a while. Now the Core respects the relating association part as well when performing an update operation involving topic references.

See #341.
See #785.

[Jörg Richter <jri@…>]

In 377afead6e084865b9d160217a9d69d43cbd4c20/deepamehta:

Core: refactor AttachedChildTopics? code (#341).

See #341.

[Malte]

Associations, Aggregations, Compositions will need arbitrary (many different) customTypeAssocs on instance-level and not _pre-defined_. Definitions are type-level. The desired support of the wikidata plugin for this ticket was to extend the Core API at AssociationModel?-level and not on the AssociationDefinitionModel?-level and i thought you were on the right track (because i just took notice of "custum assoc types on instance-level" and that's why i didnt care any longer about the details of this ticket.

Now i see that i was wrong and i am sorry that i could not support you in this. This implementation was conceptualized and developed with a clear webclient/user-perspective but not with a plugin developers perspective. Consequently, wikidata properties (see ​https://www.wikidata.org/wiki/Wikidata:List_of_properties) can now not become first class 'Association Types' and not benefit of dm4-core semantics such as Association, Aggregations or Compositions.

Maybe we can solve this the next time we come around this issue. Currently this issue is anyway not related to the immediate development of the wikidata plugin and thanks for your efforts.

[Malte]

Is there a way to define a custom association type (e.g. for one specific aggregation definition of a composite topic) in a declarative migration?

[jri]

Replying to Malte:

Is there a way to define a custom association type (e.g. for one specific aggregation definition of a composite topic) in a declarative migration?

Yes, I think so. Look at the Contacts module's migrations.
Sorry, I'm in a hurry ...