Version 9 (modified by jri, 13 years ago) (diff) |
---|
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. | 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 |