source: trunk/docs/xtm_json.txt

Last change on this file was 326, checked in by lgiessmann, 13 years ago

added a mark-as-deleted handler to the RESTful interface, so PSIs, ItemIdentifiers?, SubjectLocators?, Topics, Names, Variants, Occurrences, Associations and Roles can be deleted by this backend-handler; added the corresponding unit-tests

File size: 20.4 KB
Line 
1//+-----------------------------------------------------------------------------
2//+ Overview:
3//+  *Part 1: XTM - data model
4//+  *Part 2: Object summaries
5//+  *Part 3: TMCL - data model
6//+  *Part 4: Object notation for marking objects as deleted
7//+-----------------------------------------------------------------------------
8
9
10//+-----------------------------------------------------------------------------
11//+ Part 1: XTM - data model:
12//+   The first part describes the xtm's data model, here will be all elements
13//+   defined in the xtm defined as json objects and finally there will be used
14//+   as json objects in a json-fragment-object.
15//+
16//+   this json model depends on the xtm version 2.0 and contains the following
17//+   objects:
18//+    *resourceData
19//+    *variant
20//+    *name
21//+    *name
22//+    *occurrence
23//+    *topic
24//+    *role
25//+    *association
26//+    *topicStub
27//+    *fragment
28//+
29//+   At the end of this file are some expample json objects, you can also
30//+   validate json data on "http://www.jsonlint.com/".
31//+   Note all values, although they are null values e.g. the "type" field in
32//+   a name object should be set to a value - in this case "null".
33//+-----------------------------------------------------------------------------
34
35
36//+-----------------------------------------------------------------------------
37//+ resourceData
38//+-----------------------------------------------------------------------------
39{
40  "datatype" : "Text",
41  "value" : "Text"
42}
43
44
45//+-----------------------------------------------------------------------------
46//+ variant
47//+-----------------------------------------------------------------------------
48{
49  "itemIdentities" : [ "Text" , "..." ],
50  "scopes" : [ [ "PSI-1-t1", "PSI-2-t1", "..." ], [ "PSI-1-t2", "PSI-2-t2", "..." ], [ "..." ] ],
51  "resourceRef" : "Text",
52  "resourceData" : { <resourceData> }
53}
54
55
56//+-----------------------------------------------------------------------------
57//+ name
58//+-----------------------------------------------------------------------------
59{
60  "itemIdentities" : [ "Text", "..." ],
61  "type" : [ "PSI-1", "PSI-2", "..." ],
62  "scopes" : [ [ "PSI-1-t1", "PSI-2-t1", "..." ], [ "PSI-1-t2", "PSI-2-t2", "..." ], [ "..." ] ],
63  "value" : "Text",
64  "variants" : [ {<variant>}, { <...> ] }
65}
66
67
68//+-----------------------------------------------------------------------------
69//+ occurrence
70//+-----------------------------------------------------------------------------
71{
72  "itemIdentities" : [ "Text", "..." ],
73  "type" : [ "PSI-1", "PSI-2", "..." ],
74  "scopes" : [ [ "PSI-1-t1", "PSI-2-t1", "..." ], [ "PSI-1-t2", "PSI-2-t2", "..." ], [ "..." ] ],
75  "resourceRef" : "Text",
76  "resourceData" : { <resourceData> }
77}
78
79
80//+-----------------------------------------------------------------------------
81//+ topic
82//+-----------------------------------------------------------------------------
83{
84  "id" : "Text",
85  "itemIdentities" : [ "Text", "..." ],
86  "subjectLocators" : [ "Text", "..." ],
87  "subjectIdentifiers" : [ "Text", "..." ],
88  "instanceOfs" : [ [ "PSI-1-t1", "PSI-2-t1", "..." ], [ "PSI-1-t2", "PSI-2-t2", "..." ], [ "..." ] ],
89  "names" : [ { <name> }, { <...> } ],
90  "occurrences" : [ { <occurrence> }, { <...> } ]
91}
92
93
94//+-----------------------------------------------------------------------------
95//+ role
96//+-----------------------------------------------------------------------------
97{
98  "itemIdentities" : [ "Text", "..." ],
99  "type" : [ "PSI-1", "PSI-2", "..." ],
100  "topicRef" : [ "PSI-1", "PSI-2", "..." ]
101}
102
103
104//+-----------------------------------------------------------------------------
105//+ association
106//+-----------------------------------------------------------------------------
107{
108  "itemIdentities" : [ "Text", "..." ],
109  "type" : [ "PSI-1", "PSI-2", "..." ],
110  "scopes" : [ [ "PSI-1-t1", "PSI-2-t1", "..." ], [ "PSI-1-t2", "PSI-2-t2", "..." ], [ "..." ] ],
111  "roles" : [ { <role> }, { <...> } ]
112}
113
114//+-----------------------------------------------------------------------------
115//+ topicStub
116//+-----------------------------------------------------------------------------
117{
118  "id" : "Text",
119  "itemIdentities" : [ "Text", "..." ],
120  "subjectLocators" : [ "Text", "..." ],
121  "subjectIdentifiers" : [ "Text", "..." ]
122}
123
124
125//+-----------------------------------------------------------------------------
126//+ fragment
127//+    The field tmIds should have only one tm-id in the list, because
128//+    there will be used only the first, if the fragment is an incoming one
129//+    outgoing fragments have a list with more tmIds but at least one
130//+-----------------------------------------------------------------------------
131{
132  "topic" : { <topic> },
133  "topicStubs" : [ { <topicStub> }, { <...> } ],
134  "associations" : [ { <association> }, { <...> } ],
135  "tmIds" : [ "id-1", "id-2", "..." ]
136}
137
138
139//+-----------------------------------------------------------------------------
140//+ Part 2: Object summaries
141//+   The second part contains object summaries of exisiting objects in
142//+   isidorus.
143//+
144//+    *psiSummary
145//+    *topicSummary
146//+-----------------------------------------------------------------------------
147
148
149//+-----------------------------------------------------------------------------
150//+ psiSummary
151//+    The json list is made of inner json-lists.
152//+    Every inner json list represents one topic with all psis owned by the
153//+    topic. The outer list represents a set of all topics exist in isidorus.
154//+-----------------------------------------------------------------------------
155[ [ "topic-1-psi-1", "topic-1-psi-2", <...> ], [ "topic-2-psi-1", "topic-2-psi-2", <...> ], <...> ]
156
157
158//+-----------------------------------------------------------------------------
159//+ topicSummary
160//+    Contains the topic id,subjetcIdentifiers, itemIdentities,
161//+    subjectLocators, nameSummaries and occurrenceSummaries
162//+-----------------------------------------------------------------------------
163{
164  "id" : "Text",
165  "itemIdentities" : [ "Text", "..." ],
166  "subjectLocators" : [ "Text", "..." ],
167  "subjectIdentifiers" : [ "Text", "..." ],
168  "instanceOfs" : [ [ "PSI-1-t1", "PSI-2-t1", "..." ], [ "PSI-1-t2", "PSI-2-t2", "..." ], [ "..." ] ],
169  "names" : [ "name-1", "name-2", <...> ],
170  "occurrences" : [ "occurrence-1", "occurrence-2", <...>]
171}
172
173
174//+-----------------------------------------------------------------------------
175//+ topic map overview - node
176//+    Contains a list of trees, that represents a topic map by representing
177//+    all valid topics and their super-subtypes and type-instance
178//+    relationships.
179//+-----------------------------------------------------------------------------
180{
181  "topic" : ["psi-1", "psi-2"],
182  "isType" : <boolean>,
183  "isInstance" : <boolean>,
184  "instances" : [ <node> ]
185}
186
187
188//+-----------------------------------------------------------------------------
189//+ topic map overview - treeview
190//+    Contains alist of nodes.
191//+-----------------------------------------------------------------------------
192[ <node>, <node>, <...> ]
193
194
195//+-----------------------------------------------------------------------------
196//+ Part 3: TMCL - data model
197//+   This part explains how the tmcl-rules/suggestions of isidorus are
198//+   sent via HTTP as JSON-data.
199//+-----------------------------------------------------------------------------
200
201
202//+-----------------------------------------------------------------------------
203//+ exclusiveInstances
204//+    This message constains a list of topics represented as a list of topic
205//+    psis which are exclusive instances for the owner.
206//+-----------------------------------------------------------------------------
207{
208  "owner" : ["psi-1", "..."],
209  "exclusives" : [ [ "topic-1-psi-1", "topic-2-psi-2", "..." ], [ "topic-2-psi", "..." ], <...> ]
210}
211
212
213//+-----------------------------------------------------------------------------
214//+ simpleConstraint
215//+    This object contains a regexp member with the regular expression of the
216//+    constraint, a cardMin member with the minimum cardinality of
217//+    the referenced element which is represented as an unsignedInt
218//+    and a cardMax member which describes the maximum cardinality of this
219//+    element, this member contains an unsignedInt or the string
220//+    "MAX_INT".
221//+-----------------------------------------------------------------------------
222{
223  "regexp" : "regular expression",
224  "cardMin" : "unsigned integer in string representation",
225  "cardMax" : "unsigned integer in string representation or the string MAX_INT"
226}
227
228
229//+-----------------------------------------------------------------------------
230//+ subjectIdentifierConstraint
231//+    This object contains a regexp member with the regular expression of the
232//+    subjectIdentifier, a cardMin member with the minimum cardinality of
233//+    this subjectIdentifier in a topic which is represented as an unsignedInt
234//+    and a cardMax member which describes the maximum cardinality of this
235//+    subjectIdentifier, this member contains an unsignedInt or the string
236//+    "MAX_INT".
237//+-----------------------------------------------------------------------------
238<simpleConstraint>
239
240
241//+-----------------------------------------------------------------------------
242//+ subjectLocatorConstraint
243//+    This object contains a regexp member with the regular expression of the
244//+    subjectLocator, a cardMin member with the minimum cardinality of
245//+    this subjectLocator in a topic which is represented as an unsignedInt
246//+    and a cardMax member which describes the maximum cardinality of this
247//+    subjectLocator, this member contains an unsignedInt or the string
248//+    "MAX_INT".
249//+-----------------------------------------------------------------------------
250<simpleConstraint>
251
252
253//+-----------------------------------------------------------------------------
254//+ scopeConstraint
255//+    The scopeConstraint-Object contains a list of all available scopes of
256//+    for an association/name/occurrence element - this depends where this
257//+    json-onbject is contained.
258//+    The member availableScopeTypes contains a list of lists of topics in
259//+    form of psi-lists.
260//+    cardMin defines the minimum number of all scopes of the parent element
261//+    (association/name/occurrence).
262//+    cardMax defines the maximum number of all scopes of the parent element.
263//+-----------------------------------------------------------------------------
264{
265  "scopeTypes" : [ [ [ "psi-1-1", "psi-1-2", "..." ], [ "subtype-psi-1", "..." ], <...> ], [ "psi-2-1" "..."], <...> ],
266  "cardMin" : "unsigned integer in string representation",
267  "cardMax" : "unsigned integer in string representation or the string MAX_INT"
268}
269
270
271//+-----------------------------------------------------------------------------
272//+ topicNameConstraint
273//+    nametypescope constains the original nametype and all valid subtypes
274//+    with the specific scope constraints.
275//+    constraints contains the constraints for the owner topic.
276//+    Note scopeConstraints is a list, because, the can be more scope
277//+    constriants, e.g. one constraints wants 2 scopes of the type "en", and
278//+    "de", and another, wants 3 scopes of the type "fr", "pl" and "sp".
279//+-----------------------------------------------------------------------------
280{
281  "nametypescopes" : [ {
282                         "nameType" : [psi-1, psi-2, "..." ],
283                         "scopeConstraints" : [ <scopeConstraints> ]
284                       },
285                       {
286                         "nameType" : [subtype-1-psi-1, subtype-1-psi-2, "..." ],
287                         "scopeConstraints" : [ <scopeConstraints> ]
288                       },
289                       <...>
290                     ]
291  "constraints" : [ <simpleConstraint>, < ... > ]
292}
293
294
295//+-----------------------------------------------------------------------------
296//+ uniqueOccurrenceConstraint
297//+    This object owns a regexp member with the regular expression of the
298//+    occurrence which should be unique. So only occurrences that match the
299//+    occurrenceType and the regexp will be checked.
300//+    occurrenceType represents the topictype of the occurrence.
301//+    cardMin describes the minimum number of all matched occurrences within
302//+    all instances of this topictype's instances.
303//+    cardMax describes the maximum number of all matched occurrences within
304//+    all instances of this topictype's instances.
305//+-----------------------------------------------------------------------------
306<simpleConstraint>
307
308
309//+-----------------------------------------------------------------------------
310//+ topicOccurrenceConstraint
311//+    occurrenceTypes contains a list of a json-sub-object. This sub-object
312//+    contains an occurrenceType a specific list of scopeConstraints for
313//+    the occurrenceType and a scpecific datatypeConstraint which contains
314//+    the datatype for the occurrenceType.
315//+    The entire list of occurrenceTypes contains the not only the
316//+    original occurrenceType but also the subtypes of this occurrenceType.
317//+    constraints is a constraint list of depending to the owner topic.
318//+    unqiqueConstraint is a list of uniqeConstraints which also depends on
319//+    the owner topic.
320//+-----------------------------------------------------------------------------
321{
322  "occurrenceTypes" : [ {
323                          "occurrenceType" : [ "psi-1", "psi-2", "..." ],
324                          "scopeConstraints" : [ <scopeConstraints> ],
325                          "datatypeConstraint" : "datatype"                       
326                        },
327                        {
328                          "occurrenceType" : [ "subtype-1-psi-1", "subtype-1-psi-2", "..." ],
329                          "scopeConstraints" : [ <scopeConstraints> ],
330                          "datatypeConstraint" : "datatype"                       
331                        },
332                        <...>
333                      ],
334  "constraints" : [ <simpleConstraints>, <...>],
335  "uniqueConstraints" : [ <uniqueConstraints>, <...> ]
336}
337
338
339//+-----------------------------------------------------------------------------
340//+ associationRoleConstraint
341//+    This object defines a list of psis of the roletype topic of which
342//+    the role is an instance of.
343//+    cardMin and cardMax defines the number of roles with the defined roletype
344//+    in an association of a certain associationtype (the objects owner).
345//+-----------------------------------------------------------------------------
346{
347  "roleType" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-1-psi-1", "..."], <...> ],
348  "cardMin" : "unsigned integer in string representation",
349  "cardMax" : "unsigned integer in string representation or the string MAX_INT"
350}
351
352
353//+-----------------------------------------------------------------------------
354//+ rolePlayerConstraint
355//+    Defines the player of a certain role with a given type in an association
356//+    of a given type.
357//+    palyers is the psi-list representation of a list of  all available
358//+    players.
359//+    roleTypes is a list of topics represented by a list of psi-lists.
360//+    cardMin and cardMax defines the number of times the topicType (= player)
361//+    can be the player in a role of a given type (= roleTypes) in an
362//+    association of a given type (= objects owner).
363//+-----------------------------------------------------------------------------
364{
365  "playerType" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-1-psi-1", "..." ], <...> ],
366  "players" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "topic-2-psi-1", "..."], <...> ],
367  "roleType" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-psi-1", "..." ], <...> ],
368  "cardMin" : "unsigned integer in string representation",
369  "cardMax" : "unsigned integer in string representation or the string MAX_INT"
370}
371
372
373//+-----------------------------------------------------------------------------
374//+ otherRoleConstraint
375//+    This JSON-Object defines the number and types of (other-) roles in an
376//+    association of a given type with a role of a give type.
377//+    roleType is a allowed role with the player topicType.
378//+    otherRoleType is the second role with the player otherTopicType.
379//+    The values cardMin and cardMax defines the cardinality of otherRoleType.
380//+-----------------------------------------------------------------------------
381{
382  "playerType" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-1-psi-1", "..." ], <...> ],
383  "players" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "topic-2-psi-1", "..."], <...> ] ],
384  "roleType" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-psi-1", "..." ], <...> ],
385  "otherPlayerType" : [ [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-1-psi-1", "..." ], <...> ],
386  "otherPlayers" : [ "topic-psi-1", "topic-psi-2", "..." ], [ "topic-2-psi-1", "..."], <...> ] ],
387  "otherRoleType" : [ "topic-psi-1", "topic-psi-2", "..." ], [ "subtype-psi-1", "..." ], <...> ],
388  "cardMin" : "unsigned integer in string representation",
389  "cardMax" : "unsigned integer in string representation or the string MAX_INT"
390}
391
392
393//+-----------------------------------------------------------------------------
394//+ associationConstraints
395//+    The associationConstraint describes how an association of a given type
396//+    has to be defined.
397//+    associationRoleTypeConstraint constains all available roletypes for this
398//+    association.
399//+    rolePlayerConstraint constains all players for certain roles of a given
400//+    type.
401//+    associationTypeScopes contains all available scopes for this association.
402//+-----------------------------------------------------------------------------
403{
404  "associationType" : [ "topic-psi-1", "topic-psi-2" ],
405  "associationRoleConstraints" : [ <associationRoleConstraint>, <...> ],
406  "rolePlayerConstraints" : [ <rolePlayerConstraints>, <...> ],
407  "otherRoleConstraints" : [ <otherRoleConstraint>, <...> ],
408  "scopeConstraints" : { <scopeConstraint> }
409}
410
411
412//+-----------------------------------------------------------------------------
413//+ topicConstraint
414//+    The topicConstraint contains the members:
415//+    *exclusiveInstances which contains a topic-list of topic-psis depending
416//+     on the users exclusive-instance-constraints
417//+    *subjectIdentifierConstraints which defines the subjectIdentifiers
418//+    *subjectLocatorConstraints which defines the subjectLocators
419//+    *topicNameConstraints which defines the topic names
420//+    *topicOccurrenceConstraints which defines the topic occurrences
421//+    *uniqueOccurrenceConstraints which defines the uniqueness of topic
422//+     occurrences
423//+-----------------------------------------------------------------------------
424{
425  "exclusiveInstances" : <exclusiveInstances>,
426  "subjectIdentifierConstraints" : [ <subjectIdentifierConstraint>, <...> ],
427  "subjectLocatorConstraints" : [ <subjectLocatorConstraint>, <...> ],
428  "topicNameConstraints" : [ <topoicNameConstriant>, <...> ],
429  "topicOccurrenceConstraints" : [ <topicOccurrenceConstraint>, <...> ],
430  "abstractConstraint" : <boolean>
431}
432
433
434//+-----------------------------------------------------------------------------
435//+ fragmentConstraint
436//+    This JSON-Object contains all constraints necessary for an entire
437//+    fragment.
438//+    topicConstraint contains an object with all constraints of all baseTypes
439//+    of the mainTopic.
440//+    associationConstraints contains a list of all association constraints
441//+    depending on all baseTypes of the main topic.
442//+-----------------------------------------------------------------------------
443{
444  "topicConstraints" : <topicConstraint>,
445  "associationsConstraints" : [ <associationConstraints>, <...> ]
446}
447
448
449
450//+-----------------------------------------------------------------------------
451//+  *Part 4: Object notation for marking objects as deleted
452//+    *Topic
453//+    *PSI
454//+    *ItemIdentifier
455//+    *SubjectLocator
456//+    *Name
457//+    *Variant
458//+    *Occurrence
459//+    *Association
460//+    *Role
461//+-----------------------------------------------------------------------------
462Topic:
463{
464  \"type\":\"Topic\",
465  \"delete\":<topic>  //only the topic's identifiers are evaluated
466}
467
468PSI:
469{
470  \"type\":\"PSI\",
471  \"delete\":\"PSI-value\"
472}
473
474Item-Identifier:
475{
476  \"type\":\"ItemIdentity\",
477  \"delete\":\"ItemIdentity-value\"
478}
479
480Subject-Locator:
481{
482  \"type\":SubjectLocator\",
483  \"delete\":\"SubjectLocator-value\"
484}
485
486Name:
487{
488  \"type\":\"Name\",
489  \"parent\":<Topic>, // the topic-identifiers are enough
490  \"delete\":<Name>
491}
492
493Variant:
494{
495  \"type\":\"Variant\",
496  \"parent\":<Name>, // the full name that is needed for TMDM equality
497  \"parentOfParent\":<Topic>, // the topic-identifiers are enough
498  \"delete\"
499}
500
501Occurrence:
502{
503  \"type\":\"Occurrence\", // the full occurrence that is neede for full TMDM equality
504  \"parent\":<Topic>, // the topic-identifiers are enough
505  \"delete\":<Occurrence>
506}
507
508Association:
509{  \"type\":\"Association\",
510   \"delete\":<Association> // the full association that is neede for full TMDM equality
511}
512
513Role:
514{
515  \"type\":\"Role\",
516  \"parent\":<Association>, // the full association that is neede for full TMDM equality
517  \"delete\":<Role> // the full role that is neede for full TMDM equality
518}
Note: See TracBrowser for help on using the repository browser.