JSON Export of Wiki Keys (Key Start, Switch, Image Switch etc.)

Used templates

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

• Key Start
  • Decision Horizontal
  • Lead
• Switch
• ImageSwitch

JSON

Legend:
[ ]   → array
{ }   → object
"":"" → pair (key : value)
  "type": "decisiontree | html | switch | imageswitch" → vertical bar | means “or”. 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
           └ "html"         representation of a Wiki page
                            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"
           ├ "wiki_page_title_glossary" ────┬→ suffix _glossary is a glossary page
           ├ "wiki_page_title_glossary_fragment-id"
           ├ "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"

    metadata: {"":"", "":""}
    ├ title:           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:          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, 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:         the main creator(s) of a key, i.e. the ones to be cited as primary authors in the title line.
    ├ description:     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:       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:    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”)
    subheading:  (html) subheading to all alternatives
    remarks:     (html)
    statements_intro_text:  (html) intro text or preceding text to all alternative statements
    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  
    next_code:    (plain text) next content[].decision[].code
    statement:    (html) statement of this decision
    remarks:      (html)
    description:  (html)
    occurrence:   (html)
    
    result: {"":"", "":""}
    ├ next_id:         (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
    ├ text:            (html) text of result
    ├ ref:             (plain text; ref OR url not both) wiki_page_name#optional-fragment-id
    ├ url:             (plain text; ref OR url not both) external URL
    ├ scientific_name: (plain text | html)
    ├ synonyms:        (, list as plain text | html)
    ├ common_names:    (, list as plain text)
    └ qualifier:       (plain text | html) result qualifier, e.g. “male” or “incl. Agenus, Bgenus”

    collapsed_media_footer: (html) footer text to all collapsed images / media
    media: [{"":"", "":""}, {"":"", "":""}]
    ├ 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
    ├ caption:         (html)
    ├ label:           (plain text) figure label
    ├ url_420px:       URL to 420px sized media
    ├ url_1000px:      URL to 1000px sized media
    ├ custom_height:   a specific height is used
    ├ custom_width:    a specific width is used
    ├ custom_url:      URL to the specified sized media
    ├ url_maxres:      URL of media with highest resolution
    ├ mimetype:        mime type of this media file
    ├ error:           any error that occurs during export that is worth reporting
    └ meta_url:        URL of meta data page

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": "(html) source(s) of the key",
20                 "status": "(html) working status",
21                 "title": "(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": "subheading to all alternatives",
32                     "statements_intro_text": "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": "(html) statement of this decision alternative",
39                             "remarks": "(html)",
40                             "description": "(html) detailed description",
41                             "occurrence": "(html)",
42                             "result": [
43                                 {
44                                     "next_id": "next step of determination, i.e. next_id to either content.decision.id or content.id",
45                                     "text": "(html) text of result",
46                                     "ref": "local page (ref or url, not both)",
47                                     "url": "external page (ref or url, not both)",
48                                     "scientific_name": "(plain text | html)",
49                                     "synonyms": "(plain text as , list)",
50                                     "common_names": "(plain text as , list)",
51                                     "qualifier": "(plain text | html) result qualifier, e.g. “male”"
52                                 }
53                             ],
54                             "collapsed_media_footer": "(html) footer text to all collapsed images / media",
55                             "media": [
56                                 {
57                                     "type": "primary | large_primary | collapsed",
58                                     "mimetype": "image/jpeg",
59                                     "caption": "(html)",
60                                     "label": "(plain text) figure label",
61                                     "url_420px": "http:\/\/species-id.net\/o\/media\/b\/b5\/Paul_Williams_BumblebeeID_tail_yellow-white.jpg",
62                                     "url_1000px": "http:\/\/species-id.net\/o\/media\/b\/b5\/Paul_Williams_BumblebeeID_tail_yellow-white.jpg",
63                                     "custom_height": "121px",
64                                     "custom_width": "43px",
65                                     "custom_url": "http:\/\/species-id.net\/o\/media\/b\/b5\/Paul_Williams_BumblebeeID_tail_yellow-white.jpg",
66                                     "url_maxres": "http:\/\/species-id.net\/o\/media\/b\/b5\/Paul_Williams_BumblebeeID_tail_yellow-white.jpg",
67                                     "meta_url": "http:\/\/species-id.net\/openmedia\/File:Paul_Williams_BumblebeeID_tail_yellow-white.jpg"
68                                 }
69                             ]
70                         },
71                         { … NEXT_ALTERNATIVE … },
72                         { … NEXT_ALTERNATIVE … }
73                     ]
74                 },
75                 { … NEXT_DECISION … },
76                 { … NEXT_DECISION … }
77             ]
78         },
79         { … NEXT_CONTENT … },
80         { … NEXT_CONTENT … }
81     ]
82 }

id, next_id, 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_id 

referring to content[…].id or content[…].decision[…].id
The id of the next_id may be a decision in the same content object, or a decision in another content object.

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

 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_id":"(optional) referring to content[].id or content[].decision.id"
14           }
15         ]
16       ]
17     }
18   ]
19 }

Determination walk through

Going step by step through a key is accomplished by:

• using content[…].decision[…].alternative[…].result.next_id

The next_id refers to

• content[].id or
• 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_id is empty, then there can be further references:

• a result.ref (=reference to a localref Wiki page) 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:

<span class="cluetip other-classes"><a href="glossary_page_name">…</a></span> is changed to

<span class="cluetip other-classes"><a href="glossary_page_name_glossary" class="glossary localref">…</a></span> 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: 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:

<span class="leadontext"><a href="#Lkey_5">…</a></span> <span class="leadontext"><a href="#LmySpecialKey_5">…</a></span> is changed to

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