wiki:DataFormat
Last modified 12 years ago Last modified on 12.07.2012 04:21:15

  1. Data Format
    1. Topic
      1. Example 1: a simple topic
      2. Example 2: a complex topic
      3. Example 3: an even more complex topic
    2. Association
      1. Example 1: an association that connects 2 topics
      2. Example 2: an association that connects a topic with an association
    3. Topic Type
      1. Example 1: a simple topic type
      2. Example 2: a complex topic type
    4. Association Type
      1. Example: an association type
    5. Association Definition
    6. View Configuration
    7. Topic Map
    8. Index Modes

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 Controls how the topic instance's payload is indexed. Default is no indexing. 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

The association type format is analog to the Topic Type format:

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

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

"dm4.core.text"
"dm4.core.number"
"dm4.core.boolean"
"dm4.core.html"
"dm4.core.composite"
index_mode_uris Controls how the association instance's payload is indexed. Default is no indexing. 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 association types: a list of child type definitions. Each definition references a child type and provides further declarations, e.g. cardinalities.

For simple association 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: an association type

{
  "id": 10,
  "uri": "dm4.core.instantiation",
  "type_uri": "dm4.core.assoc_type",
  "value": "Instantiation",
  "composite": {
  },
  "data_type_uri": "dm4.core.text",
  "index_mode_uris": [
  ],
  "assoc_defs": [
  ],
  "label_config": [
  ],
  "view_config_topics": [
    {
      "id": 792,
      "uri": "",
      "type_uri": "dm4.webclient.view_config",
      "value": "",
      "composite": {
        "dm4.webclient.color": "rgb(41, 194, 225)"
      }
    }
  ]
}

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.

Association definition objects appear in the assoc_defs property of complex Topic Types and complex Association Types.

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

TODO: better explain the view configuration concept.

Each DeepaMehta client application might involve different presentation paradigms.

Topic types, association types, and association definitions can be attached with View Configuration Topics.

The standard DeepaMehta webclient defines its presentation model by the means of the complex topic type dm4.webclient.view_config. There are a number of simple child topic types:

Child Type Target Description Data Type
dm4.webclient.icon Topic Type The icon to render the topic instances. Text (a path)
dm4.webclient.color Association Type The color to render the association instances, e.g. "#29c2e1" or "rgb(41,194,225)". Text (a CSS color code)
dm4.webclient.add_to_create_menu Topic Type Display topic type in "Create" menu? Boolean
dm4.webclient.is_searchable_unit Topic Type Stop at this topic type when parentize a search result item. Boolean
dm4.webclient.editable Topic Type Display field on form page? Boolean
dm4.webclient.viewable Topic Type Display field on info page? Boolean
dm4.webclient.js_page_renderer_class Topic Type
Association Type 		The class that renders the info/form page Text (a class name)
dm4.webclient.js_field_renderer_class Simple Topic Type The class that renders the field on the info/form page Text (a class name)
dm4.webclient.rows Simple Topic Type of data type "Text" or "HTML" The number of rows of the field on the form page Number

Topic Map

Index Modes