Latest revision as of 23:14, 13 April 2017

This is a draft documentation meant for discussion and improvement of exporting Wiki Key data to JSON format. This is used by NaturLotse/NaturePilot software

Used templates

For most recent documentation of template parameters see on German project page Offene-Naturführer (documentation in English):

JSON

Many objects can have multiple languages themselves they are encoded as an unbounded sequence of objects, e.g. the text object of the result object (added 2014-03-14):

'result' : { 
  'text': 
  [                                                                        ─┐
    {'language': 'de', 'content': 'deutscher Inhalt'},                      │
    {'language': 'en', 'content': 'English content'},                       ├ written in short: [LANG]
    {'language': 'language-code', 'content': 'language specific content'}   │
  ]                                                                        ─┘
}

Legend:

[ ]    → array
[LANG] → array of language specific content (see example above)
{ }    → object
"":""  → pair (key : value), example:
  "type": "decisiontree | html | switch | imageswitch" 
       → vertical bar | means “or”, i.e. values can be either: decisiontree, html, switch or imageswitch

Error messages

Note that objects can have "error":"error message" if there is any error worth reporting. Objects that can contain errors:

media.error
metadata.error

content[…]

content [ {…}, {…} ]
  Definition: Unbounded sequence of objects.
  Elements:
    type: type of content
           ├ "decisiontree" representation of a key (Key Start)
           ├ "switch"       representation of Switch
           ├ "imageswitch"  representation of ImageSwitch
           ├ "glossary"     representation of a glossary page^[1] (content as <div id="content">…</div> not the whole doctype)
           └ "html"         representation of a Wiki page^[2] (content as <div id="content">…</div> not the whole doctype)
                            a) a context page (=Wiki page without keys)
                            b) a Wiki page, different kind of pages: a result page, taxon page
    fragment_id: fragment identifier of the key (id attribute of a HTML tag; optional; set in most cases, but: content.type:"html" has no fragment_id)
    id:   (plain text) unique identifier with the possible values:
           ├ "wiki_page_title_decisiontree" ┬→ suffix _decisiontree is a decisiontree or switch or imageswitch
           ├ "wiki_page_title_decisiontree_fragment-id"^[3]
           ├ "wiki_page_title_glossary" ────┬→ suffix _glossary is a glossary page
           ├ "wiki_page_title_glossary_fragment-id"^[3]
           ├ "wiki_page_title_wikipage" ────┬→ suffix _wikipage is a context page (=wiki page mixed with keys) or a result page
           └ "wiki_page_title_wikipage_fragment-id"^[3]

    metadata: {"":"", "":""}
    ├ title:           [LANG] the title of the key, presented as a heading above the key
    ├ audience:        optional, the intended audience: 12 yr old school children, 6th grade, university students, general public, experts, etc.
    ├ geoscope:        optional, geographic scope
    ├ source:          [LANG] optional, published source citation, if key itself was previously published. If key was newly developed, based on multiple publications, these should normally not be cited here.
    ├ contributor:     (["", ""] optional array) a list of later co-authors or editors who contributed significantly to the improvement of the key. This includes contributors adding images. (is deprecated "edited_by")
    ├ creator:         (["", ""] array) the main creator(s) of a key, i.e. the ones to be cited as primary authors in the title line.
    ├ description:     [LANG] optional, full text description, elaborating information not yet captured in title, geoscope, audience etc.
    ├ status:          optional, progress and status, e.g. "incomplete", "finished"
    ├ language:        abbreviated language code (set explicitly or Wiki default is used)
    ├ collaboration_limited_to: a list of names, to which the collaboration shall be limited. Empty means: "collaboration: open" should be shown.
    ├ initiated_by:    optional, initiator(s) of a key project, who does not wish to be cited as primary author
    ├ general_review_by: optional, persons that have acted as reviewers and quality control editors
    ├ nomreview_by:    optional, nomenclatural review
    ├ expert_review_by: optional, review by a taxonomic expert of the group.
    ├ icon_url:        a non-default icon / pictogram representing the key in lists, overviews etc. (e.g. floating left or right), default icon is a sized version of http://species-id.net/openmedia/File:Determination_logo_2_question.svg (40x40px?)
    ├ publicity:       [LANG] optional, advertise for an association, e.g. the German Deutscher Jugendbund für Naturbeobachtung or the author’s web page
    ├ recommendation_group: provide a recommendation for the end user (categorisation)
    ├ taxon_name:      optional
    ├ common_names:    [LANG] optional
    ├ parent_key_id:   optional, a key's parent link, it refers to content.id (parent_key_id or parent_key_url, not both)
    ├ parent_key_url:  optional, external url (parent_key_id or parent_key_url, not both)
    ├ parent_key_text: optional, display text for the link to the parent key
    ├ parent_taxon:    optional, the next higher taxonomic level
    ·
    ├ error:           optional, if there is any error worth reporting
    ├ modified:        get the last touched timestamp (ISO 8601 format with no timezone: 1986-02-09T20:00:00Z)
    ├ created:         oldest revision timestamp of this page (ISO 8601 format with no timezone: 1986-02-09T20:00:00Z)
    ├ source_url:      URL of the page / key
    ├ root_decisiontree_id: id for the “start” key, given only for the JSON package metadata
    └ page_context_id: optional, id to extra page content (that means the key is embedded by page content, i.e. it has a page context, e.g. references, notes, introduction, non-key-text etc. surrounding the key)
  Example: see below

content[…].decision[…]

decision: [ {…}, {…} ]
  Definition: Bounded sequence of objects and representation of content.type "decisiontree", "switch" or "imageswitch" (sequence order is that order on the original Wiki page).
  Elements:
    id: (plain text) unique identifier with the possible values:
                 ├ "wiki_page_title_decision" (=first decision)
                 ├ "wiki_page_title_decision_fragment-id" (=first decision of a key on a Wiki page having a non-default fragment-id, i.e. multiple keys on a page)
                 ├ "wiki_page_title_decision_decision-code" (=any decision but not the first )
                 └ "wiki_page_title_decision_fragment-id_decision-code" (=any decision but not the first )
    nid:         (integer) numeric record identifier
    code:        (plain text) code of the decision e.g.:
                 1 for 1*, 1'', 1 a OR
                 A for A 1, A*
                 (“A” or “1” but not “1a”)
                  content[…].decision[…].code
                  │ content[…].decision[…].alternative[…].code
                  ┴─┴──
                  2*
                  3*
                  4*
                  A*
                  2 a
                  3 b
                  4 c
                  A'
                  B'
                  C'
    subheading:  [LANG] (html) subheading to all alternatives^[4]
    remarks:     [LANG] (html)
    statements_intro_text:  [LANG] (html) intro text or preceding text to all alternative statements^[5]
    alternative: [ {…}, {…} ] → see decision[…].alternative[…]
    ├ result:   {…} → see decision[…].alternative[…]
    ├ media:    {…} → see decision[…].alternative[…]
    ├ "":"",
    └ "":""
  Example: see below

content[…].decision[…].alternative[…]

alternative: [ {…}, {…} ]
  Definition: Unbounded sequence of objects describing alternatives of a decision.
  Elements:
    id: (plain text) unique identifier with the possible values:
                  ├ "wiki_page_title_decision_decision-code_alternative-index"
                  └ "wiki_page_title_decision_fragment-id_decision-code_alternative-index"
    nid:          (integer) numeric record identifier
    code:         (plain text) code of the alternative e.g.:
                  ** OR a OR - OR empty, e.g. * for 2* or A*, '' for 2'', a for 2 a 
                  content[…].decision[…].code
                  │ content[…].decision[…].alternative[…].code
                  ┴─┴──
                  2*
                  2**
                  2***
                  A*
                  2 a
                  2 b
                  2 c
                  A'
                  A''
                  A'''
    next_code:    (plain text) next content[].decision[].code
    statement:    [LANG] (html) statement of this decision
    remarks:      [LANG] (html)
    description:  [LANG] (html)
    occurrence:   [LANG] (html)
    
    result: {"":"", "":""}
    ├ next_decision:    (optional plain text) allows determination step by step. If it is empty, then determiantion stops and a result should be present
    │                   referring to content[].id or content[].decision.id^[6](Changed 2013-08-07)
    ├ next_content:     (optional plain text; next_content OR url not both) next content.id wiki_page_name_wikipage (Changed 2013-08-07)
    ├ html_fragment_id: (optional) pointing to a html fragment id (Added 2013-08-07)
    ├ url:              (plain text; next_content OR url not both) external URL
    ├ id:               (plain text) an (external) identifier, should be used for the final decision only. Recommended usage e.g.: «AphiaID:990076» 
    ├ text:             [LANG] (plain text | html) text of result (see also talk )
    ├ scientific_name:  (plain text | html)
    ├ synonyms:         (, list as plain text | html)
    ├ common_names:     [LANG] (, list as plain text)
    └ qualifier:        [LANG] (plain text | html) result qualifier, e.g. “male” or “incl. Agenus, Bgenus”

    collapsed_media_footer: (html) footer text to all collapsed images / media
    media: [{"":"", "":""}, {"":"", "":""}] (Changed 2013-07-26. See new media collection below. see also talk )
    ├ type: media type can have the following values
    │        ├ "primary"       media/images always visible 
    │        ├ "large_primary" media/images always visible but with large size
    │        └ "collapsed"     hidden or collapsible media/images
    ├ local_file_id:   (=id of file name to be localized)
    ├ caption:         [LANG] (html)
    └ label:           [LANG] (plain text) figure label

media[…]

Collection of all media.

media: [{"":"", "":""}, {"":"", "":""}]
  Definition: Unbounded sequence of objects.
  Elements:
    local_file_id:  (=id of local file name)
    meta_url:       URL of meta data page (page context, containing the metadata like author, license, etc.)
    modified:       get the last upload timestamp (ISO 8601 format with no timezone: 1986-02-09T20:00:00Z)
    error:          any error that occurs during export that is worth reporting
    small: {"":"", "":""} media up to … 420px
    ├ url:          URL for max 420px sized media (smaller if only smaller available)
    ├ height:       height of this variant
    ├ width:        width of this variant
    └ mimetype:     mime type of this of this variant
    large: {"":"", "":""} media up to 421px … 1000px
    ├ url:          URL for max 1000px sized media (missing if largest is 420, smaller than 1000 if only 421-999px available)
    ├ height:       height of this variant
    ├ width:        width of this variant
    └ mimetype:     mime type of this of this variant 
    max:  {"":"", "":""}
    ├ url:          URL of media with highest possible resolution, missing if largest is <1001px 
    ├ height:       height of this variant
    ├ width:        width of this variant
    └ mimetype:     mime type of this of this variant

Example

Elaboration of the decision object used above:

 1 {
 2     "metadata": {
 3         "root_decisiontree_id":"id for the root key or “start” key",
 4         "…":"…"
 5     },
 6     "content": [
 7         {
 8             "type": "html",
 9             "html": "(html) the first content element of type 'html' contains usually the wiki page stripped off any keys in the page. Keys are stored in content[].decision",
10             "fragment_id": "",
11             "id": "(unique) content-id"
12         },
13         {
14             "metadata": {
15                 "audience": "(plain text , list)",
16                 "edited_by": "(plain text , list) of authors",
17                 "geoscope": "(plain text , list)",
18                 "icon_url": "icon-url",
19                 "source": [{"language":"en", "content","(html) source(s) of the key"}],
20                 "status": [{"language":"en", "content","(html) working status"}],
21                 "title": [{"language":"en", "content","(html) title text"}],
22                 "source_url": "URL of the key (only), can have a fragemnt identifier #thekey-something",
23                 "page_context_id": "identifier to a content.id, i.e. the embedding (outer) wiki page"
24             },
25             "type": "decisiontree | html | switch | imageswitch",
26             "fragment_id": "(HTML id attribute) fragment identifier of the key",
27             "decision": [
28                 {
29                     "id": "(unique) decision-id",
30                     "code": "1",
31                     "subheading": [{"language":"en", "content","subheading to all alternatives"}],
32                     "statements_intro_text": [{"language":"en", "content","intro text to all alternative statements"}],
33                     "alternative": [
34                         {
35                             "id": "(unique) alternative-id",
36                             "code": "a",
37                             "next_code": "(next decision[].code) 2",
38                             "statement": [{"language":"en", "content","(html) statement of this decision alternative"}],
39                             "remarks": [{"language":"en", "content","(html)"}],
40                             "description": [{"language":"en", "content","(html) detailed description"}],
41                             "occurrence": [{"language":"en", "content","(html)"}],
42                             "result": [
43                                 {
44                                     "text": [{"language":"en", "content","(html) text of result"}],
45                                     "next_decision": "next step of determination",
46                                     "next_content": "local content page (next_content or url, not both)",
47                                     "url": "external page (next_content or url, not both)",
48                                     "scientific_name": "(plain text | html)",
49                                     "synonyms": "(plain text as , list)",
50                                     "common_names": [{"language":"en", "content","(plain text as , list)"}],
51                                     "qualifier": [{"language":"en", "content","(plain text | html) result qualifier, e.g. “male”"}]
52                                 }
53                             ],
54                             "collapsed_media_footer": [{"language":"en", "content","(html) footer text to all collapsed images / media"}],
55                             "media": [
56                                 {
57                                     "local_file_id": "Paul_Williams_BumblebeeID_tail_yellow-white.jpg (refering to media collection)",
58                                     "type": "primary",
59                                     "caption": [{"language":"en", "content","(html)"}],
60                                     "label": [{"language":"en", "content","(plain text) figure label"}]
61                                 }
62                             ]
63                         },
64                         { … NEXT_ALTERNATIVE … },
65                         { … NEXT_ALTERNATIVE … }
66                     ]
67                 },
68                 { … NEXT_DECISION … },
69                 { … NEXT_DECISION … }
70             ]
71         },
72         { … NEXT_CONTENT … },
73         { … NEXT_CONTENT … }
74     ],
75     "media": [
76         {
77             "local_file_id": "Paul_Williams_BumblebeeID_tail_yellow-white.jpg",
78             "modified": "2009-06-16T21:24:17Z",
79             "meta_url": "http:\/\/species-id.net\/openmedia\/File:Paul_Williams_BumblebeeID_tail_yellow-white.jpg",
80             "small": {
81                 "mimetype": "image\/jpeg",
82                 "height": 121,
83                 "width": "43",
84                 "url": "http:\/\/species-id.net\/o\/media\/b\/b5\/Paul_Williams_BumblebeeID_tail_yellow-white.jpg"
85             }
86         }
87     ]
88 }

id, next_decision, next_content, nid

id: all ids are unique text-string IDs in the JSON document (=candidate key). The following ids are defined
content[…].id
content[…].decision[…].id
content[…].decision[…].alternative[…].id
next_decision: referring to content[…].decision[…].id it points to the first decision. (changed 2013-08-07)
next_content: referring to content[…].id (changed 2013-08-07)
page_context_id: content[…].metadata.page_context_id referring to a content[…].id of a key’s context page (a key can be embedded in a page and may have a context content)
parent_key_id: optional, a key's parent link, it refers to content.id
nid: (unused for now) numerical (unique and constant) record id (see also talk )

 1 {
 2   "metadata":{"":"", "":""},
 3   "content":[
 4     {
 5       "id":"(optional: mandatory only for type=html)"
 6     },
 7     {
 8       "decision":[
 9         "id":"(mandatory)",
10         "alternative":[
11           "id":"(mandatory)",
12           "result":{
13             "next_decision":"(optional) referring to content[].decision.id"
14           }
15         ]
16       ]
17     }
18   ]
19 }

Determination walk through

Going step by step through a key^[7] is accomplished by:

using content[…].decision[…].alternative[…].result.next_decision

The next_decision refers to …

content[].decision[].id

All id strings in the JSON document are unique. Those identifiers can be maintained to be constant after key changes only if decisions are just appended, they don't keep constant if decision sequences are interchanged.

If next_decision is empty, then there can be further references:

a result.next_content (=reference to a local content page^[8]) or
a result.url (=reference to an external URL) or
neither of both but a result.text telling that there is only a result (then display of mobilekey2_keyresult_help_todo) or the maximum number of children of a key package is reached (then display of mobilekey2_error_stop_childkeys). Note: result.text has always a value, details see Discussion result.text.

Cross links

There can be cross links between key statements and a wiki page that is the context page of that key, i.e. the key or multiple keys are embedded in a Wiki page. Cross links are be referred to as follows (it may change if there is a better solution). Note that all href attributes should be rawurlencoded.

Ordinary local cross links

It links to the content.id of that wiki page and CSS class pagecontext is added:

<a href="#local-id">…</a> is changed to

<a href="wiki_page_name_wikipage#local-id" class="wikipage localref">…</a>

pointing to

a content.type:"html"
with content.id:"wiki_page_name_wikipage"
#local-id points to an HTML tag id of that object content.html

Glossary cross links

It links to the content.id of that glossary wiki page and CSS class glossary is added:

<a href="glossary_page_name">…</a> is changed to

<a href="glossary_page_name_glossary" class="glossary localref">…</a>

pointing to

a content.type:"glossary"
with content.id:"glossary_page_name_glossary"
optionally a #local-id to an HTML tag id of that content.html may be present for the use of CSS pseudo selector :target

Key cross links

Key cross links: provide a pointer to a numbered decision.code of a single access key (originally template:Lead Link used for template:Lead). They point to content.decision.id not to content.decision.alternative.id:

<a href="#Lkey_5">…</a>
<a href="#LmySpecialKey_5">…</a>

is changed to

<a href="wiki_page_name_decision_5" class="decision localref">…</a>
pointing to content.decision.id:"wiki_page_name_decision_5"
<a href="wiki_page_name_decision_mySpecialKey_5" class="decision localref">…</a>
pointing to content.decision.id:"wiki_page_name_decision_mySpecialKey_5"

Inline images

It links to the content.id of that wiki page and CSS class pagecontext is added:

<img src="path/to/source.jpg" /> is changed to

<img data-recommended-filesize="small OR large OR void" data-local-file-id="local-file-id of media[] collection" src="source.jpg" />

see also talk

Background

        *
      /   \ 
     /     * 
    /     / \ 
   /     /\  \ 
  /         /|\ 
 *·←··     / | \ 
/ \   ·   /\ |\ \ 
   \   ·         \    
  / \   ·         \
 /\  \   ·         *
    /|\   ·       /|\ 
           ·     / |
            ·   /\ |\
             ·←

The decision tree represents decisions (having two or more alternatives) and it can be chained by representing multiple blocks of keys written by different authors (star symbol *). It …

is chained (can contain multiple keys)
is directed, not-cyclic (always a final alternative) and
can contain cross links (go back to another entry point, previously discarded; arrow ←)

Each block of a decision tree can be of content.type "decisiontree", "switch" or "imageswitch" and parameter content.decision.alternative.result.next_decision allows to step through all alternatives.

Log notes

Changed 2017-04-13

html only contains <div id="content"></div>, not the whole doctype. Note that #firstHeading corresponds to the wiki page title

Changed 2014‎-03-14

added multi-language objects denoted here with [LANG]

Changed 2013-08-07

result.next_id → next_decision: referring to content[…].decision[…].id it points to the first decision

result.ref → result.next_content: referring to content[…].id

new result.html_fragment_id

Changed 2013-07-26

media object was restructured: content[…].decision[…].alternative[…].media[…] uses a local_file_id and refers to the media collection object media in the root. It contains data of small, large and maximum sized media file version. see also talk

Annotations

↑ a link pointing to a glossary has CSS class a.glossary.localref <a class="glossary localref">…</a>
↑ a link pointing to a Wiki page has CSS class a.wikipage.localref <a class="wikipage localref">…</a>
↑ ^3.0 ^3.1 ^3.2 Internal note: fragment-id is appended only when a Wiki template did define a non-default id. Defaults are: "key" ({{Key Start}}), "switch" ({{Switch}}), "imageswitch" ({{ImageSwitch}})
↑ Internal note: subheading_1, subheading_2 of Template:Switch trigger a new decision.
↑ choose a more concise name? statement_intro_text or
↑ is empty when max_key_recursion_depth (=50) is reached
↑ a “key” has a content[…].type of either "imageswitch" or "switch" or "decisiontree"
↑ <a href="wiki_page_name_id_wikipage" class="wikipage localref">…</a>

tt>content.type:"glossary"br/> pointing to

[1] ting to a glossary has CSS class a.glossary.localref <span class="cluetip"><a class="glossary localref">…</a></span>

[2] ting to a Wiki page has CSS class a.wikipage.localref <a class="wikipage localref">…</a>

[fragment-id-note-3] 3.0 ^3.1 ^3.2 Internal note: fragment-id is appended only when a Wiki template did define a non-default id. Defaults are: "key" ({{Key Start}}), "switch" ({{Switch}}), "imageswitch" ({{ImageSwitch}})

[4] Internal note: subheading_1, subheading_2 of Template:Switch trigger a new decision.

[5] se a more concise name? statement_intro_text or

[6] s empty when max_key_recursion_depth (=50) is reached

[7] “key” has a content[…].type of either "imageswitch" or "switch" or "decisiontree"

[8] <a href="wiki_page_name_id_wikipage" class="wikipage localref">…</a>

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

Difference between revisions of "JSON Export of Wiki Keys (Key Start, Switch, Image Switch etc.)"

Latest revision as of 23:14, 13 April 2017

Contents