APE Webservice

Introduction

This document describes the APE Webservice (version 6.6 and higher). The service translates an ACE text into a Discourse Representation Structure (DRS) and other logical forms. It can be accessed over the HTTP protocol using GET or POST. The URL of the service is

http://attempto.ifi.uzh.ch/ws/ape/apews.perl

An example of a GET query is

http://attempto.ifi.uzh.ch/ws/ape/apews.perl?text=Every+man+is+a+human.&solo=drspp

which returns the pretty-printed DRS of the ACE sentence Every man is a human..

Note that the APE executable (ape.exe) supports the -httpserver flag which lets you start your own webservice. See more in the APE documentation.

The rest of this document specifies the input and the output of the service and lists some example clients.

Input

The following table lists all the parameters that can be used as input to APE. A correct query has to minimally specify the ACE text (by text or file). The c-parameters (those whose name starts with c) can be used to configure which types of outputs are produced. The solo-parameter can be used to specify a single output type. In this case, all the c-parameters are ignored.

Parameter Value Description
textstringACE text
fileURLURL of an ACE text
ulextextstringUser lexicon
ulexfileURLURL of a user lexicon
ulexreloadon | offReload the user lexicon. This has effect only if ulexfile is specified.
noclexon | offIgnore the lexicon entries that are built into into the webservice (i.e. rely only on the user lexicon and/or guessing).
guesson | offGuess the word-class (common noun, verb, adjective, adverb) of unknown words. I.e. a text containing unknown words is not rejected, instead, the parser tries to figure out the word-class of such words automatically. Note that the parser does not try to lemmatize such words, e.g. unknown plural nouns would be stored in the DRS in the plural form, not in their lemma (i.e. singular) form.
uriURIOntology URI (only used in the OWL outputs).
cdrson | offOutput the DRS as a Prolog term.
cdrsxmlon | offOutput the DRS in XML.
cdrsppon | offOutput the DRS in pretty-printed form in plain text.
cdrshtmlon | offOutput the DRS in pretty-printed form in HTML.
cparaphraseon | offOutput a paraphrase that is a ``best-effort'' combination of paraphrase1 and paraphrase2.
cparaphrase1on | offOutput a paraphrase that uses full sentences instead of relative clauses.
cparaphrase2on | offOutput a paraphrase that uses relative clauses instead of full sentences. This paraphrase can currently handle if-then sentences that do not contain any modifiers, of-constructions, ditransitive verbs and noun phrase coordination. Note: experimental.
ctokenson | offOutput tokens as a Prolog list of lists of atoms.
csentenceson | offOutput sentences as a Prolog list of atoms.
csyntaxon | offOutput simplified syntax trees as a Prolog list.
csyntaxppon | offOutput simplified syntax trees in pretty-printed form.
csyntaxdon | offOutput plain syntax trees as a Prolog list (for debugging).
csyntaxdppon | offOutput plain syntax trees in pretty-printed form (for debugging).
cowlfsson | offOutput OWL/SWRL in the functional representation as a Prolog term.
cowlfssppon | offOutput OWL/SWRL in the functional representation pretty-printed.
cowlrdfon | offOutput OWL/SWRL in the RDF/XML representation. DEPRECATED
cowlxmlon | offOutput OWL/SWRL in the XML representation.
cfolon | offOutput the standard first-order logic (FOL) representation of the DRS (as a Prolog term).
cpnfon | offOutput the standard FOL representation (Prenex Normal Form) of the DRS (as a Prolog term).
ctptpon | offOutput the TPTP representation of the DRS. This format is directly usable as the input format for most FOL theorem provers.
crulemlon | offOutput the RuleML representation of the DRS.
solodrs | drsxml | drspp | drshtml | paraphrase | paraphrase1 | paraphrase2 | tokens | sentences | syntax | syntaxpp | syntaxd | syntaxdpp | owlfss | owlfsspp | owlrdf | owlxml | fol | pnf | tptp | ruleml Output just one output component. For drspp, paraphrase, paraphrase1, paraphrase2, syntaxpp, syntaxdpp, owlfsspp, the output is in plain text; for drs, tokens, sentences, syntax, syntaxd, owlfss, fol, pnf, the output is in Prolog term notation, for drsxml, drshtml, owlrdf, owlxml, ruleml the output is in XML. For tptp, the output is in TPTP.

All flags are off by default.

The value of ulexfile is a URL of the user lexicon (see the ACE lexicon specification). When used for the first time, the user lexicon is downloaded from the given URL and stored locally. The subsequent queries that use the same URL for the user lexicon do not force the lexicon to be reloaded. If the lexicon is changed, it has to be explicitly reloaded by including ulexreload=on in the query.

Output

The most important output component is the DRS. See the documentation in the DRS Report. The webservice also provides additional data about the tokenization and syntax of the input text, as well as its paraphrases (in ACE). These outputs help to understand whether the translation into the DRS is the intended one.

Additionally, the webservice can convert the DRS into other logical languages: standard representations of first-order logic, OWL/SWRL, TPTP, and RuleML.

In case the input is not a well-formed ACE text, an error message is returned. Also, if the input was successfully translated into DRS, but the DRS was not supported by the further conversion (to a paraphrase, OWL, TPTP, etc.), an error message is returned.

Solo output

In case solo is set, the APE Webservice generates just one output. This makes integration with applications which accept URLs as input easier. Each output has its corresponding Internet media type.

Parameter Media type Format
drs text/plain DRS (Prolog term)
drsxml text/xml DRS (XML document)
drspp text/plain DRS (ASCII picture)
drshtml text/html DRS (HTML picture)
paraphrase text/plain ACE
paraphrase1 text/plain ACE
paraphrase2 text/plain ACE
tokens text/plain List of lists (sentences) of tokens (Prolog list of lists of atoms)
sentences text/plain List of sentences (Prolog list of atoms)
syntax text/plain Simplified syntax trees (Prolog term)
syntaxpp text/plain Simplified syntax trees (ASCII picture)
syntaxd text/plain Plain syntax trees (Prolog term)
syntaxdpp text/plain Plain syntax trees (ASCII picture)
owlfss text/plain OWL/SWRL (Prolog term)
owlfsspp text/plain OWL/SWRL (ASCII picture)
owlrdf text/xml OWL/SWRL (RDF/XML document) DEPRECATED
owlxml text/xml OWL/SWRL (XML document)
fol text/plain FOL (Prolog term)
pnf text/plain PNF (Prolog term)
tptp text/plain TPTP
ruleml text/xml RuleML (XML document)

Note that the outputs that are denoted by 'Prolog term', 'Prolog list', etc. are serialized Prolog terms which can be read back into true terms by Prolog-based clients when using atom_to_term/3.

In case of errors or warnings, only the error/warning messages are output (in XML).

Combined output

Unless solo is set, APE outputs an XML document (content type text/xml) encoded in UTF-8 character set with a root element apeResult. This output is formally specified by an XML Schema apews_output.xsd. The children of the root element are an element duration which reports the time that APE spent on processing the ACE text (in seconds), an element messages which is used to output warning and error messages, and a subset of elements drs, drsxml, drspp, drshtml, paraphrase, paraphrase1, paraphrase2, tokens, sentences, syntax, syntaxpp, syntaxd, syntaxdpp, owlfss, owlfsspp, owlrdf, owlxml, fol, pnf, tptp, ruleml.

The output of the webservice could look like the following.

<?xml version='1.0' encoding='UTF-8'?>
<apeResult>
<duration tokenizer="0.01" parser="0.05" refres="0.0"/>
<tokens>[['Some', frogs, are, green, '.'], ['Kermit', is, a, frog, '.']]</tokens>
<drs>drs([A, B, C, D, E], [object(A, frog, countable, na, geq, 2)-1/2,
property(B, green, pos)-1/4, predicate(C, be, A, B)-1/3,
object(D, frog, countable, na, eq, 1)-2/4,
predicate(E, be, named('Kermit'), D)-2/2])</drs>
</apeResult>

Error messages

If the translation fails, APE returns an empty DRS (drs([],[])) and a list of error messages. Then an element messages is output.

<?xml version="1.0" encoding="UTF-8"?>
<apeResult>
<duration tokenizer="0.09" parser="0.2" refres="0.1"/>
<drs>drs([], [])</drs>
<tokens>[['Every', man, waits, '.'], ['He', eats, '.']]</tokens>
<messages>
    <message importance="error" type="refres" sentence="2" token="1"
        value="Unresolved anaphor: he"
	repair="Identify correct accessible antecedent."/>
</messages>
</apeResult>

An ACE text can be erroneous for several reasons:

  1. the input contained a wordform that was not described in the lexicon(s),
  2. the input violated the ACE syntax rules,
  3. the input was syntactically correct but anaphoric references could not be resolved.

Note that the exact location of the syntax error is pinpointed.

<?xml version="1.0" encoding="UTF-8"?>

<messages>
  <message
    importance="error"
    type="sentence"
    sentence="1"
    token="4"
    value="A man runs <> very fast."
    repair="This is the first sentence that was not ACE.
            The sign <> indicates the position where parsing failed."/>

Note that sometimes errors occur after a correct DRS has been generated. E.g. the translation of ACE texts into OWL is based on the DRS, but not all DRSs are supported in this translation. In this case an error message is reported (which has a type owl).

Example clients

We have implemented some clients of the APE Webservice to demonstrate APE's interface and how it can be used in different programming languages. Feel free to extend or embed this code.

Since all major programming languages have libraries available for sending queries over HTTP, it is probably possible to use the APE Webservice from your favorite language. If you implement an improved version of the existing clients or a new client in another programming language and want to share your work, please contact us.

2013-07-31