JSON Format

Overview

This wiki maintains the JSON format for the agfk API. The JSON format adheres to the following guiding principles:

• Underscores should be used in place of spaces or hypens
• Dictionaries store data that can/should be uniquely referenced
• Ordered lists store data that are typically referenced as part of a group
• Ordered lists should only be used if it is possible that the data will have a multiplicity greater than one otherwise plain text should be use
  • e.g. each concept node will only have one ID so an ordered list should not be used to specify the ID, while each node can have more than one dependency, so an ordered list should be used even if the given node only has one dependency.
• Empty strings, lists, or dictionaries should be used to indicate the absence of data

Format

{
    "nodes": {
        "node1_id": {*node_content*},
        "node2_id": {*node_content*},
        ...
    } 
}

where *node_content* is the following dictionary

{
    "title": "node_title",                  % plain text
    "summary": "node_summary",              % plain text
    "pointers": "pointer_text",             % Textile formatted text
    "dependencies": [*dep1*, *dep2*, ...],  % ordered list of dependencies (see below)
    "resources": [*rsrc1*, *rsrc2*, ...],   % ordered list of resources (see below)
    "questions": ["q1", "q2", ...]          % ordered list of plain text comprehension questions
}

each dependency in "dependencies" is the following dictionary

{
    "from_tag": "node_id",           % plain text id of node
    "to_tag": "dep_node_id",          % plain text id of parent
    "reason": "reason_for_dep"     % plain text [or null if not available TODO should return empty string, not null]
}

and each resource in resources is the following dictionary

{
    "title": "resource_title",      % resource title
    "location": "location_info",    % location of info in resource, e.g. section 4.3
    "resource_type": "rtype",       % text description of resource type, e.g. 'textbook'
    "free": 1,                      % boolean to indicate whether resource is free access
    "edition": "str"                % edition number of resources
    "url": "http-url",              % URL of the resource
    "authors": ["a1", "a2"],        % list of authors of the given resource
    "dependencies": [dep1, dep2],   % list of dependencies for the given resource
    "mark": ["star"],               % list of marks for the given resources
    "extra": ["ec1", "ec2"]         % list of extra-info strings for the resource
    "note": ["n1", "n2"]            % list of notes for the given resource
}

where location, free, and title are the required fields

Notes

• The field "nodes" should always be present in the returned data, even if the returned data is for a single node

Discussion Point

• What should the comprehension keys contains? Do we want each ckey to have a unqiue server side ID?
• Should we include empty fields? (colorado's perspective: yes: consistency, no: speed/size; most graphs shouldn't have speed/size issues so I opt for yes) -colorado
  • actually, I would like to keep the data transfer small (think mobile phone, ipads, etc) and think we should not include empty fields