<div id="api_guide">
  <h2>Input Data Formats</h2>

  <div id="input_format_contents">
    <h3>Table of Contents</h3>
    <ul>
      <li><a href="#intro">Introduction</a></li>
      <li><a href="#tab">Tab Delimited Input</a></li>
      <li><a href="#xml">XML Input</a></li>
      <li><a href="#json">JSON Input</a></li>
      <li><a href="#validations">Data Validations</a></li>
    </ul>
  </div>

  <div id="intro" class="formats">
    <h3>Introduction</h3>
    <p>In this section we describe the various input formats supported by the <code>data</code> parameter to each of the <code>find</code>
    and <code>find_nhsbt</code> API calls. Currently there are three supported input formats, namely tab
    delimited, XML and JSON. The input format used does not need to correspond with the format of the output
    data - it may be best to only use one format for consistency though.</p>
   </div>

  <div id="tab">
    <h3>Tab Delimited Input</h3>
    <p>A tab delimited file has four columns separated by tabs (or in fact spaces). This was the first format
      used to model the input and as such it only supports a subset of the features.
      In particular, the specification of donor ids are not supported with this format. If donor ids are required to
      be returned then either <a href="#json">JSON</a> or <a href="#xml">XML</a> must be used.

    <p>An example of data modelled using tab delimited format is shown below:</p>
    <pre class="brush: xml">
1	2	3	65
1	3	1	65
1	4	2	49
2	1	2	45
2	5	1	45
3	1	1	25
4	2	1	55
4	3	3	55
4	5	4	55
5	2	1	29
    </pre>

    <p>We now give a explanation of this format. Consider line 1: here we have that a donor for patient
    1 is compatible with patient 2 and the score between this donor and patient 2 is 3. The final column on the
    line indicates the donor age, so in this case we have that the donor for patient 1 at line 1 has age 65. However,
    we note that patient 1 must have two donors as the donor represented by line 3 has age 49. This can cause confusion
    when a patient may have multiple donors of the same age as we need some way of identifying which donor was
    actually chosen. To handle this situation the <a href="#json">JSON</a> and <a href="#xml">XML</a> formats allow
    the specification of a donor id and as such both these formats are preferred to the tab delimited.</p>

 <!--   <h4>Five Columns</h4>
    <p>As indicated above it is possible that a patient may have several donors of the same age. In order to
    identify the donor that was matched as part of any exchange we allow the four column format above to be
    extended with a fifth column that holds a donor id. An an example of such a file is shown below:</p>

    <pre class="brush: xml">
1	2	3	45  1
1	3	1	45  1
1   3   5   45  2
1	4	2	45  1
2	1	2	36  3
2	5	1	36  3
3	1	1	19  4
4	2	1	28  5
4	3	3	28  5
4	5	4	28  5
5	2	1	63  6
    </pre>

    <p>In this example we can see that patient 1 has two donors (lines 2 and 3) both of age 45 both of whom are compatible
    with patient 3. Now if we return data that only states that [1,3] is a pairwise exchange, it is
    not immediate what donor we should choose (it would involve going and looking at the scores). However, if
    a donor id is supplied we can simply return the donor id as part of the output data (as seen in the
    in the <%= link_to 'Output Formats', {:action => 'output_format'} %> page).</p>
-->
  </div>

  <div id="xml">
    <h3>XML</h3>
    <p>Using XML as an input format allows meaning to be attached to the individual elements unlike the tabbed
    format which relies on the reader of any such data to be intimately aware of the format (which, given
    the confusing nature of the column meanings, it can sometimes be difficult). As such the use of a structured
    format such as XML is preferred.</p>

    <p>A sample input file is shown below using XML:</p>

    <pre class="brush: xml">
&lt;?xml version="1.0" ?&gt;
&lt;data&gt;
	&lt;entry donor_id="1"&gt;
		&lt;sources&gt;
      &lt;source&gt;1&lt;/source&gt;
    &lt;/sources&gt;
    &lt;dage&gt;65&lt;/dage&gt;
    &lt;matches&gt;
      &lt;match&gt;
        &lt;recipient&gt;2&lt;/recipient&gt;
        &lt;score&gt;3&lt;/score&gt;
      &lt;/match&gt;
      &lt;match&gt;
        &lt;recipient&gt; 3 &lt;/recipient&gt;
        &lt;score&gt;1&lt;/score&gt;
      &lt;/match&gt;
      &lt;match&gt;
        &lt;recipient&gt;4&lt;/recipient&gt;
        &lt;score&gt;2&lt;/score&gt;
      &lt;/match&gt;
    &lt;/matches&gt;
  &lt;/entry&gt;

  &lt;entry donor_id="2"&gt;
    &lt;sources&gt;
      &lt;source&gt;2&lt;/source&gt;
    &lt;/sources&gt;
    &lt;dage&gt;45&lt;/dage&gt;
    &lt;matches&gt;
      &lt;match&gt;
        &lt;recipient&gt; 1&lt;/recipient&gt;
        &lt;score&gt;2&lt;/score&gt;
      &lt;/match&gt;
      &lt;match&gt;
        &lt;recipient&gt; 5 &lt;/recipient&gt;
        &lt;score&gt;1&lt;/score&gt;
      &lt;/match&gt;
    &lt;/matches&gt;
  &lt;/entry&gt;

  &lt;entry donor_id="3"&gt;
    &lt;sources&gt;
      &lt;source&gt;3&lt;/source&gt;
    &lt;/sources&gt;
    &lt;dage&gt;25&lt;/dage&gt;
    &lt;matches&gt;
      &lt;match&gt;
        &lt;recipient&gt;1&lt;/recipient&gt;
        &lt;score&gt;1&lt;/score&gt;
      &lt;/match&gt;
    &lt;/matches&gt;
  &lt;/entry&gt;

  &lt;entry donor_id="4"&gt;
    &lt;sources&gt;
      &lt;source&gt;4&lt;/source&gt;
    &lt;/sources&gt;
    &lt;dage&gt;55&lt;/dage&gt;
    &lt;matches&gt;
      &lt;match&gt;
        &lt;recipient&gt; 3 &lt;/recipient&gt;
        &lt;score&gt;2&lt;/score&gt;
      &lt;/match&gt;
      &lt;match&gt;
        &lt;recipient&gt; 2 &lt;/recipient&gt;
        &lt;score&gt;3&lt;/score&gt;
      &lt;/match&gt;
      &lt;match&gt;
        &lt;recipient&gt; 5 &lt;/recipient&gt;
        &lt;score&gt;4&lt;/score&gt;
      &lt;/match&gt;
    &lt;/matches&gt;
  &lt;/entry&gt;

  &lt;entry donor_id="5"&gt;
    &lt;sources&gt;
      &lt;source&gt;5&lt;/source&gt;
      &lt;source&gt;6&lt;/source&gt;
    &lt;/sources&gt;
    &lt;dage&gt;30&lt;/dage&gt;
    &lt;matches&gt;
      &lt;match&gt;
        &lt;recipient&gt;4&lt;/recipient&gt;
        &lt;score&gt;2&lt;/score&gt;
      &lt;/match&gt;
      &lt;match&gt;
        &lt;recipient&gt; 2 &lt;/recipient&gt;
        &lt;score&gt;1&lt;/score&gt;
      &lt;/match&gt;
    &lt;/matches&gt;
  &lt;/entry&gt;

  &lt;entry donor_id="6"&gt;
    &lt;dage&gt;29&lt;/dage&gt;
    &lt;altruistic&gt;true&lt;/altruistic&gt;
    &lt;matches&gt;
      &lt;match&gt;
        &lt;recipient&gt;7&lt;/recipient&gt;
        &lt;score&gt;10&lt;/score&gt;
      &lt;/match&gt;
    &lt;/matches&gt;
  &lt;/entry&gt;

  &lt;entry donor_id="7"&gt;
    &lt;sources&gt;
      &lt;source&gt;7&lt;/source&gt;
    &lt;/sources&gt;
    &lt;dage&gt;29&lt;/dage&gt;
  &lt;/entry&gt;

&lt;/data&gt;
    </pre>

    <p>Looking at the data above we see that the <code>&lt;entry&gt;</code> tag is used to hold information
    about the set of patients that a donor (identified by the <code>donor_id</code> attribute) is compatible with.
    We first note that the <code>donor_id</code> attribute of the <code>&lt;entry&gt;</code> element is required; this
    is in contrast to the tab delimited form where donor ids were not specified. Within the entry tag we see the
    following elements:</p>
    
    <ul class="entry_descr">
      <li> <code>&lt;sources&gt;</code> contains a set of <code>&lt;source&gt;</code> elements where each source
        element holds an id of a patient whose donor is identified by the <code>donor_id</code> attribute. Unless
        the donor is an altruistic donor then the <code>&lt;sources&gt;</code> element must be supplied; failure to
        supply at least one source element will result in an error being returned. When the donor is an altruistic
        donor then supplying a source id is optional. If a source id is supplied, the <code>&lt;sources&gt;</code>
        element must consist of a single <code>&lt;source&gt;</code>, otherwise
        the <code>&lt;sources&gt;</code> element must not be present in the <code>&lt;entry&gt;</code>.
        For example, in first entry above
        we can see that donor 1 is the willing donor for patient 1. We note that although unlikely, it's possible
        that a given donor may be a willing donor for more than one patient on the list, hence why the format allows for multiple
        <code>&lt;source&gt;</code> elements within the <code>&lt;sources&gt;</code> tag.</li>

      <li> <code>&lt;dage&gt;</code> holds the age of the donor identified by the <code>donor_id</code>
        attribute.</li>
      
      <li><code>&lt;altruistic&gt;</code> holds the value true if the donor specified by <code>donor_id</code> is an altruistic
      donor. If the element is not present or false then then we obviously have a non-altruistic donor.</li>

      <li> <code>&lt;matches&gt;</code> contains a set of <code>&lt;match&gt;</code> elements that show the
      set of patients that are compatible with the donor identified by <code>donor_id</code>.
      A <code>&lt;match&gt;</code> element contains two sub-entries namely
      <code>&lt;recipient&gt;</code> and <code>&lt;score&gt;</code>. Here <code>&lt;recipient&gt;</code> holds the
      id of a potential recipient of donor <code>donor_id</code>'s kidney and <code>&lt;score&gt;</code> holds the
        score of the potential transplant from <code>donor_id</code> to <code>&lt;recipient&gt;</code>. For example,
      in the first <code>&lt;entry&gt;</code> in the sample file above, the donor with id 1 is compatible with patients
      2, 3 and 4, with scores 3, 1, 2 respectively. We note that it is possible to omit the <code>&lt;matches&gt;</code> element
      from an entry. </li>
    </ul>
  </div>

  <div id="json">
    <h3>JSON</h3>
    <p>One problem with formatting input using <a href="xml">XML</a> is the increased verbosity of modelling the input data -
    for very large amounts of data the needless opening and closing of tags will have a significant effect on the
    amount of traffic passed over the network. To save bytes but retain the structure of the data
    we can use JSON as our input format.</p>

    <p>The same data shown in the <a href="xml">XML example</a> is presented below using JSON.</p>

    <pre class="brush: js">
{ "data" :
	{
    "1" : { "sources" : [1],
            "dage" : 65,
            "matches" : [ { "recipient" : 2, "score" : 3},
                          { "recipient" : 3, "score" : 1},
                          { "recipient" : 4, "score" : 2} ]},
    "2" : { "sources" : [2],
            "dage" : 45,
            "matches" : [ { "recipient" : 1, "score" : 2},
                          { "recipient" : 5, "score" : 1} ]},

    "3" : { "sources" : [3],
            "dage" : 25,
            "matches" : [ { "recipient" : 1, "score" : 1},
                          { "recipient" : 5, "score" : 1} ]},

    "4" : { "sources" : [4],
            "dage" : 55,
            "matches" : [ { "recipient" : 2, "score" : 3},
                          { "recipient" : 3, "score" : 2},
                          { "recipient" : 5, "score" : 4} ]},

    "5" : { "sources" : [5,6],
            "dage" : 30,
            "matches" : [ { "recipient" : 2, "score" :	1},
                          { "recipient" : 4, "score" : 2} ]},
    
    "6" : { "altruistic": true,
            "dage" : 29,
            "matches" : [ { "recipient" : 7, "score" :	10} ]},

    "7" : { "sources" : [7],
            "dage": 29 }
	}
}
    </pre>

    <p>The JSON format consists of a key called <code>data</code> that holds a JSON object whose keys are formed
      from the list of donor ids. That is each entry in the JSON data array has the format:</p>

    <pre>
      "integer_value_representing_a_donor" :
            { "sources" : an_array_of_ids_representing_the_patients_
                          that_the_donor_is_willing_to_donate_for

              "dage" : age_of_the_donor,

              "altruistic": true_if_the_donor_is_altruistic,

              "matches" : an_array_of_objects_where_each_object_
                          holds_information_about_compatible_patients }
    </pre>


      <p>Looking at the example above we have that the donor with id 1 is a donor for patient 1,
      his age is 65, and he is compatible with patients 2, 3 and 4 with scores 3, 1 and 2 respectively. As with the
      <a href="#xml">XML Input Format</a> the <code>sources</code> key can hold more than one source and so is represented
      as an array - donor 5 shows a donor with multiple sources. Each non-altruistic donor must have at least one source,
      and every donor must supply a donor age in the <code>dage</code> field. Altruistic donors are identified by adding the
      <code>altruistic</code> key with the value <code>true</code> to a donor's JSON object. Donor 6 in the example above
      shows a typical entry for an altruistic donor - notice that an altruistic donor need not supply any sources (however you
      any source id supplied will be returned consistently in the output). To show the set of patients that are
      compatible with a donor we use the <code>matches</code> element. The <code>matches</code> element holds an array
      of JSON objects where each object in this array represents a compatible patient, whose id is stored in the <code>recipient</code>
      field, and the score between this donor and patient (stored in the <code>score</code> field). We can see this in the
      example above by noting that donor 4 is compatible with three patients: patient 2 with score 3, patient 3 with
      score 2, and patient 5 with score 4. Finally donor 7 shows a rare case where a donor need not have any <code>matches</code> key.
      </p>
  </div>

  <div id="validations">
    <h3>Data Validations</h3>

    <p>Below we outline the validations that are performed on the input data supplied to the service.
    These validations are undertaken for both the JSON and XML input formats above, if for any reason
    the data validation fails an <%= link_to("error response", {:controller => :api, :action => :output_format}) %>
    will be returned. Any elements that are specific to one data format will be indicated in the text.</p>

    <ol id="validation_list">
      <li>Checks that the syntax of any XML and JSON file is valid.</li>
      <li>Checks that the input data is contained within a <code>data</code> key/tag.</li>
      <li>For JSON format ensure that the value stored in <code>data</code> is an object and that the object's
      key, representing the donor id, can be converted to an integer.</li>
      <li>Checks that each <code>&lt;entry&gt;</code> in XML has a <code>donor_id</code> attribute whose value
      is an integer</li>
      <li>Checks that the <code>sources</code> key/tag is supplied and that it contains, in the case of JSON, an
      array of integer ids, and for XML a set of source elements whose values are integer ids.</li>
      <li>Checks that the <code>dage</code> key/tag is supplied and contains an integer whose
          value is greater than zero but smaller than 150</li>
      <li>Checks that the <code>altruistic</code> value is a boolean</li>
      <li>Checks that a <code>matches</code> key/tag is present and consists of a single entry if the
      donor is altruistic</li>
      <li>Checks that if a <code>matches</code> key/tag is supplied then it is non-empty</li>
      <li>Checks that a <code>match</code> object in XML, and a <code>matches</code> object in JSON consists
      of a <code>recipient</code> and <code>score</code></li>
      <li>Check that any <code>recipient</code> keys/tags values are integers</li>
      <li>Check that any <code>score</code> keys/tags are supplied and contains a double/float</li>
    </ol>

  </div>

</div>