wiki:DataFormat

Version 9 (modified by jri, 13 years ago) (diff)

Association Definition explained

Data Format

This page describes the data format of DeepaMehta's core objects (and some non-core objects) as retrieved via the REST API.

Note: The format used in create and update operations differs slightly. See the respective notes on the REST API page.

Topic

A topic object has always 5 properties:

Property Description Format
id A system-generated ID. A number (long), e.g. 2735
uri A globally unique identifier.
Typically assigned by human.
If no URI is assigned: an empty string.
A string of format <domain>.<project>.<name>
type_uri The URI of the topic's type. A string of format <domain>.<project>.<name>, e.g. ffnet.geomap.access_point
value For a simple topic1): the topic's payload.
Note: For a complex topic the value is derived from the composite property.
A simple value: string, int, long, or boolean.
composite For a complex topic2): a nested object representation.
(For a simple topic: an empty object.)
See examples 2 and 3 below.

1) The term simple topic refers to an instance of a simple topic type. A simple topic type is one of data type "Text", "Number", "Boolean", or "HTML". See Topic Type.

2) The term complex topic refers to an instance of a complex topic type. A complex topic type is one of data type "Composite". It is composed of child topic types (arbitrary depth).

Example 1: a simple topic

{
  "id": 2816,
  "uri": "",
  "type_uri": "dm4.contacts.city",
  "value": "Berlin",
  "composite": {
  }
}

Example 2: a complex topic

{
  "id": 2900,
  "uri": "",
  "type_uri": "dm4.files.file",
  "value": "freifunk-geomap.png",
  "composite": {
    "dm4.files.file_name": "freifunk-geomap.png",
    "dm4.files.path": "/home/jri/freifunk-geomap.png",
    "dm4.files.size": 767016,
    "dm4.files.media_type": "image/png",
    "dm4.files.content": "<img src=\"/proxy/file:%2Fhome%2Fjri%2Ffreifunk-geomap.png\"></img>"
  }
}

Example 3: an even more complex topic

{
  "id": 2735,
  "uri": "",
  "type_uri": "dm4.contacts.person",
  "value": "Jörg",
  "composite": {
    "dm4.contacts.person_name": {
      "dm4.contacts.first_name": "Jörg",
      "dm4.contacts.last_name": "Richter"
    },
    "dm4.contacts.phone_entry": {
      "dm4.contacts.phone_label": "home",
      "dm4.contacts.phone_number": "123 456 78"
    },
    "dm4.contacts.email_address": "jri@deepamehta.de",
    "dm4.webbrowser.url": "www.deepamehta.de",
    "dm4.contacts.address_entry": {
      "dm4.contacts.address_label": "home",
      "dm4.contacts.address": {
        "dm4.contacts.street": "My Street 23",
        "dm4.contacts.postal_code": "12345",
        "dm4.contacts.city": "Berlin",
        "dm4.contacts.country": "Germany"
      }
    },
    "dm4.notes.text": "<p>Software Developer</p>"
  }
}

Association

An association has 2 ends. At each end there is a topic or an association. So, an association connects either 2 topics, or 1 topic and 1 association, or 2 associations. Both ends are qualified by a Role Type.

An association has the same 5 properties as a Topic plus 2 role properties:

Property Description Format

id

See Topic

uri

type_uri The URI of the association's type. A string of format <domain>.<project>.<name>, e.g. dm4.core.aggregation

value

See Topic

composite

role_1

One association's end: a pair of a topic/association reference and a role type.

Topics are specified by ID or URI.

Associations are specified by ID.

Either

{
  "topic_id": <Topic ID>,
  "role_type_uri": <Role Type URI>
}

or

{
  "topic_uri": <Topic URI>,
  "role_type_uri": <Role Type URI>
}

or

{
  "assoc_id": <Association ID>,
  "role_type_uri": <Role Type URI>
}

role_2

The other association's end.

Example 1: an association that connects 2 topics

{
  "id": 2797,
  "uri": "",
  "type_uri": "dm4.core.composition",
  "value": "",
  "composite": {
  },
  "role_1": {
    "topic_id": 2735,
    "role_type_uri": "dm4.core.whole"
  },
  "role_2": {
    "topic_id": 2794,
    "role_type_uri": "dm4.core.part"
  }
}

Example 2: an association that connects a topic with an association

{
  "id": 2798,
  "uri": "",
  "type_uri": "dm4.core.instantiation",
  "value": "",
  "composite": {
  },
  "role_1": {
    "topic_id": 60,
    "role_type_uri": "dm4.core.type"
  },
  "role_2": {
    "assoc_id": 2797,
    "role_type_uri": "dm4.core.instance"
  }
}

Topic Type

A topic type has the same 5 properties as a Topic plus 4 type-specific ones:

Property Description Format
id See Topic
uri A globally unique identifier. Every topic type has an URI. A string of format <domain>.<project>.<name>
type_uri Fixed. "dm4.core.topic_type"
value The topic type's name. Readable by human. An arbitrary string. Can contain spaces and special characters.
composite Fixed. {}
data_type_uri The topic type's data type. That is the data type of one instance's payload.

dm4.core.composite denotes a complex topic type which is composed of child types. The other 4 data types denote a simple topic type.
One of these 5 strings:

"dm4.core.text"
"dm4.core.number"
"dm4.core.boolean"
"dm4.core.html"
"dm4.core.composite"
index_mode_uris For simple topic types: Controls how the topic instance's payload is indexed. Default is no indexing.

For complex topic types: not used.
An array with zero or more of these strings:

"dm4.core.off"
"dm4.core.key"
"dm4.core.fulltext"
"dm4.core.fulltext_key"

See Index Modes
assoc_defs For complex topic types: a list of child type definitions. Each definition references a child type and provides further declarations, e.g. cardinalities.

For simple topic types: not used.
An array of child type definitions.

See Association Definition1)
view_config_topics View models for various clients. An array of view configuration topics.

See View Configuration

1) Association Definition is a legacy term but still reflected by the property name. It should be renamed to Child Type Definition. The respective property should be renamed to child_type_defs.

Example 1: a simple topic type

{
  "id": 943,
  "uri": "dm4.webbrowser.url",
  "type_uri": "dm4.core.topic_type",
  "value": "URL",
  "composite": {
  },
  "data_type_uri": "dm4.core.text",
  "index_mode_uris": [
    "dm4.core.key",
    "dm4.core.fulltext"
  ],
  "assoc_defs": [
  ],
  "view_config_topics": [
  ]
}

Example 2: a complex topic type

{
  "id": 959,
  "uri": "dm4.webbrowser.web_resource",
  "type_uri": "dm4.core.topic_type",
  "value": "Web Resource",
  "composite": {
  },
  "data_type_uri": "dm4.core.composite",
  "index_mode_uris": [
  ],
  "assoc_defs": [
    {
      "id": 964,
      "uri": "dm4.webbrowser.url",
      "assoc_type_uri": "dm4.core.composition_def",
      "whole_topic_type_uri": "dm4.webbrowser.web_resource",
      "whole_role_type_uri": "dm4.core.whole",
      "whole_cardinality_uri": "dm4.core.one",
      "part_topic_type_uri": "dm4.webbrowser.url",
      "part_role_type_uri": "dm4.core.part",
      "part_cardinality_uri": "dm4.core.one",
      "view_config_topics": [
      ]
    },
    {
      "id": 974,
      "uri": "dm4.webbrowser.web_resource_description",
      "assoc_type_uri": "dm4.core.composition_def",
      "whole_topic_type_uri": "dm4.webbrowser.web_resource",
      "whole_role_type_uri": "dm4.core.whole",
      "whole_cardinality_uri": "dm4.core.one",
      "part_topic_type_uri": "dm4.webbrowser.web_resource_description",
      "part_role_type_uri": "dm4.core.part",
      "part_cardinality_uri": "dm4.core.one",
      "view_config_topics": [
      ]
    }
  ],
  "view_config_topics": [
    {
      "id": 988,
      "uri": "",
      "type_uri": "dm4.webclient.view_config",
      "value": "/de.deepamehta.webbrowser/images/earth.png",
      "composite": {
        "dm4.webclient.icon": "/de.deepamehta.webbrowser/images/earth.png",
        "dm4.webclient.add_to_create_menu": true,
        "dm4.webclient.is_searchable_unit": true
      }
    }
  ]
}

Association Type

Association Definition

An Association Definition represents a parent-child relationship (=association) between 2 types. The parent type is a topic type or an association type; the child type is a topic type.

Property Description Format
id The association ID.
uri Same as part_topic_type_uri.
assoc_type_uri The type of the association.
Either "composition" or "aggregation".
One of
"dm4.core.composition_def"
"dm4.core.aggregation_def"
whole_topic_type_uri URI of the parent type.
whole_role_type_uri Fixed. "dm4.core.whole"
whole_cardinality_uri Cardinality at the "parent" end.
For a composition: always "one".
For an aggregation: "one" or "many".
One of
"dm4.core.one"
"dm4.core.many"
part_topic_type_uri URI of the child type.
part_role_type_uri Fixed. "dm4.core.part"
part_cardinality_uri Cardinality at the "child" end: "one" or "many". One of
"dm4.core.one"
"dm4.core.many"
view_config_topics View models for various clients. Allows overriding the child type's view models. An array of view configuration topics.

See View Configuration

View Configuration

Topic Map

Index Modes