ACEvalidation receipts

Documentation

Operating instructions

Deployed engines (live)

Read just now from GET https://gateway-staging-d9e1dbd7.up.railway.app/v1/engines. Every receipt carries the same provenance.

ape (authority)
engineape
upstream repohttps://github.com/Attempto/APE
commit5f4d5354a45fb772763bf1a9543f508f15b28982
vendored source sha256aad00afd5613a72432b88207e92e174cf42be19c1a33058d28d58696cd5cbb1e
runtimeSWI-Prolog 9.2.9
image digestsha256:b2a10417ae125a4e8406b292aea0b57a8b504aa3603fd72589e90240cde79dbb
lexiconclex · https://github.com/Attempto/Clex @ 20960a5ce077
lexicon sha2562996fabfe0cf5a402b9ff7d76e09cb6e2fbedda51e917367c0b9f81fde6266ec
built at2026-11-18T14:52:27Z
gf (second opinion)
enginegf
upstream repohttps://github.com/Attempto/ACE-in-GF
commit92ef598db5dda9b75aa0e7fae1ed4eb2f8303f5b
vendored source sha2566e0ec3b9e077fb64e85b988f35fe175b6117ce828ca181201052a9e615b77e7a
runtimeGF 3.12.0; RGL 20260403
image digestsha256:0f1a56239471ff327b2ccee9e0effe0bd1060b24f5bb7cf510ca9df3c55e8d9f
lexiconclex · https://github.com/Attempto/Clex @ 20960a5ce077
lexicon sha25645d3f35bbc93b6a62293214d49a625ddc887bdba7e1359005bad31f1a5252c1b
grammarace+clex · concrete ClexAce
built at2026-11-18T15:10:36Z
gf_multi (translation)
enginegf
upstream repohttps://github.com/Attempto/ACE-in-GF
commit92ef598db5dda9b75aa0e7fae1ed4eb2f8303f5b
vendored source sha2566e0ec3b9e077fb64e85b988f35fe175b6117ce828ca181201052a9e615b77e7a
runtimeGF 3.12.0; RGL 20260403
image digestsha256:ee0fee24093c94c2b739243900157754fb3ac61b855125bc1e8e65092d44e8de
lexiconwords300 · https://github.com/Attempto/ACE-in-GF @ 92ef598db5dd
lexicon sha2565b7277d064ec73310d7a1f70fbda1b8d08cc51a2f8b09a3b555888e981281638
grammaracewiki_aceowl+words300 · concrete Words300Ace
built at2026-11-18T14:11:43Z

gf_multi languages: Ace Bul Cat Chi Est Fre Gre Hin Ita Mlt Pol Rus Spa Swe Urd

ACE in ten minutes

Attempto Controlled English (ACE) is English with a fixed grammar and a fixed interpretation: every ACE sentence has exactly one meaning, which the parser (APE) writes down as a discourse representation structure and reads back to you as a paraphrase. The paraphrase is the point. A receipt says the text is ACE; only you can say whether its meaning is the one you wanted.

Shape of a sentence

  • Simple: A guest pays a fee. — determiner, noun, verb, object. Every content word must be in the lexicon (Clex) or in your user_lexicon.
  • Universal rules: Every guest that leaves late pays a fee. — every, relative clauses with that/who/which.
  • Conditions: If a guest leaves late then the guest pays a fee. — if … then …; use the guest to refer back.
  • Negation and modality: No guest smokes., A guest can pay., It is false that a guest smokes.
  • Numbers, strings and variables: A room has 2 beds., A guest's name is "Ana"., There is a guest X. X waits.

What usually goes wrong

  • Unknown lowercase words are errors (Every xylo waits.); capitalised unknown words are read as proper names, with a warning.
  • Clock times, dates and units need the ACE forms; after 11:00 is not ACE as written.
  • Phrasal verbs (checks out) and plain-English shortcuts are not in the grammar; rephrase (leaves).
  • Articles before proper names and dangling the without an antecedent change the meaning; read the paraphrase.

The reference material is the Attempto group's documentation: attempto.ifi.uzh.ch/site/docs — the ACE construction rules, interpretation rules and the APE web-service description. The policy applied here is strict-v1: warnings are valid, errors are not, guessing is never used.

ACE Validation API: Operating Instructions

Derived from schemas/openapi.yaml, which governs. Base URL https://gateway-staging-d9e1dbd7.up.railway.app/v1 (Railway-generated domain, D-013. The exact host is in GET /v1/engines docs and on /docs). Auth header: Authorization: Bearer ace_live_… (create a key at /account).

1. Validate text

curl -s https://gateway-staging-d9e1dbd7.up.railway.app/v1/validate \
  -H "Authorization: Bearer $ACE_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Every man is a human."}'

Read three fields, in this order:

  1. verdict.ace_valid: is it ACE under the named parser, lexicon and policy?
  2. engines.ape.outputs.paraphrase: is this what you meant? Only you can answer that.
  3. engines.ape.messages: if invalid, each message gives sentence, token, value and a repair hint.

A 200 with ace_valid: false is a successful validation. The text is simply not ACE.

Request fields

FieldTypeDefaultNotes
textstring(required)1–10,000 chars, ≤ 200 sentences
user_lexiconstringnoneAPE lexicon lines, e.g. noun_sg(minibar, minibar, neutr). ≤ 50 KB
outputsstring[]["drs","paraphrase","gf_trees"]Also: drspp paraphrase1 paraphrase2 syntax tokens owlfss
visibilityprivate | linkprivatelink lets anyone with the id read the receipt

Adding words

curl -s https://gateway-staging-d9e1dbd7.up.railway.app/v1/validate -H "Authorization: Bearer $ACE_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Every mman is a hhuman.","user_lexicon":"noun_sg(mman, mman, masc).\nnoun_sg(hhuman, hhuman, neutr)."}'

(The example is from the APE README.) The receipt then records input.user_lexicon.sha256, so its claim is "valid under Clex plus this lexicon".

2. Fetch a receipt

GET /v1/receipts/{id}. Private receipts need the creating key.

3. Verify a receipt (no trust in our database needed)

curl -s https://gateway-staging-d9e1dbd7.up.railway.app/v1/receipts/verify -H "Content-Type: application/json" \
  -d "{\"receipt\": $(cat receipt.json), \"rerun\": true}"

signature_valid and hash_valid check that the receipt is genuine and unaltered. rerun.same_engines: false means the deployed engines have changed since the receipt was issued. That is not a failure, but the result can't be compared.

4. Translate (GF subset)

POST /v1/translate {"text":"…","to":["Fre","Swe"]}. Valid language codes: GET /v1/engines → gf_multi.languages. Works only within the ACE-in-GF subset and its ~300-word multilingual vocabulary. Otherwise 422 gf_not_covered.

5. Errors

HTTPerror.codeWhat to do
400bad_request, text_too_long, too_many_sentences, bad_user_lexiconFix the request
401unauthorizedCheck key
404not_foundWrong id, or a private receipt
422gf_not_covered, unknown_languageTranslation only
429rate_limitedWait Retry-After seconds
503engine_busy, engine_timeout, engine_unavailableRetry. For timeout, split the text

No receipt is ever issued with a 4xx/5xx.

6. CI (GitHub Action)

- uses: benmikeal/ace-api/action@v1
  with:
    files: 'rules/**/*.ace'
    api-key: ${{ secrets.ACE_KEY }}

Fails the job if any file has ace_valid: false, annotates the offending token, and writes ace-receipts.json.

Notices

This service runs the Attempto Parsing Engine (APE), © Attempto Group, University of Zurich, licensed under the GNU Lesser General Public License 3.0 (upstream Attempto/APE), with the Clex lexicon, derived from COMLEX, licensed under the GNU General Public License 3.0 (upstream Attempto/Clex), and ACE-in-GF (Attempto/ACE-in-GF) on the Grammatical Framework and its Resource Grammar Library. The engines are used as network services; their exact upstream commits, the hashes of the vendored sources as built and the lexicon hashes are in every receipt and in the engines table above. A receipt certifies only that text parses as ACE under those engines: not that a rule is correct, that its paraphrase matches the author's intent, or that any system implements it.