Firepear Informatics

Rthes Server Response Specification

This document describes and defines the format of Rthes server response payloads.

The current version is 0.

Overview

Regardless of transmission method, responses are JSON-formatted string representations of datastructures.

Some components of the response are invariant and always present. Some are variant and/or conditionally present. Care has been taken to maximize consistency.

1 — Base Response

All responses are on object, constucted as follows:

{ 
  cmd:"command",
  status:req_status,
  msg:"status explication",
  query:"user query",
  ver:res_version,
}

Base response object data definition

Field	Type	Content
cmd	String	The command which the request attempted to execute (e.g. "fetch")
status	Integer	Numeric status code
msg	String	User-oriented message string accompanying status
query	String	Arguments, if any, to cmd. May be null.
ver	Integer	RTHES response protocol version

2 — Category Response

Requests which return information about thesaurus categories add a cat object which describes the category itself.

cat:{
      id:id_num,
      disp:display_id_num,
      word:"Headword",
      alt:"Expository text",
      slist:[ sid, sid_2, ... sid_n ],
      class:class_id,
      div:division_id,
      sec:section_id,
      sub:subsection_id
    }

Category object data definition

Field	Type	Content
id	Integer	True (database) id number of category
disp	Integer	User-facing sequence number of category
word	String	Category headword
alt	String	Many categories have text which supplements the headword in conveying the meaning of the category. This is that.
slist	Array	All category responses include the database id numbers of the senses which comprise the category
class div sec sub	Integer	These are the database ids of the chunks of the Synopsis of Categories to which the category belongs.

3 — Sense List Response

Responses which return chunks of thesaurus data add a scont object which holds the contents of senses in the result set.

scont:[ 
        {
          pos:part_of_speech,
          senses: [ sense_data ]
        } ...
      ]

scont is an array of objects representing part-of-speech groupings of senses. The objects are guaranteed to have been loaded into the array in order, sorted by part of speech, and by sense order within part of speech.

Actual sense data is contained in sense_data objects within the senses array of each part-of-speech grouping. These will be formatted differently depending on the response type.

3.1 — Index Response Sense Data

Index responses will contain sense_data objects like the following:

{
  sid:sense_id,
  sord:sense_order,
  term:"term",
  alt:"headword",
  cid:category_num,
  disp:display_id_num
}

Index response sense_data object data definition

Field	Type	Content
sid	Integer	Database id of the matching sense
sord	Integer	Ordinal of the matching sense
term	String	First term of first entry of matching sense
alt	String	Headword of category, for display alongside term when it is identical to the search term.
cid	Integer	True (database) id number of category
disp	Integer	User-facing sequence number of category

3.2 — Fetch Response Sense Data

Fetch responses will contain sense_data objects like the following:

{
  id:sense_id
  ord:sense_order_num
  alt:"Sense alt text"
  subs:[
         {
           id:subsense_id,
           ser:series_flag,
           ents:[ ent, ent_2, ... ent_n ]
         } ...
       ]
}

Where ents is a list of entry objects, ordered by entry order within the subsense, and formatted as

{
  term:"term",
  ref:{
        cid:category_id,
        disp:display_id_num,
        sid:sense_id,
        sord:sense_order,
        alt:"Alt text"
      },
  notes:[
          { text:"note_text", longtext:"expanded_text" },
          ... 
        ]
}

The subobjects ref and notes only occur if the entity has a reference, or one or more notes, respectively. The longtext of the notes objects may be a null string.

Incomplete...