Who Are Active? Human and Non-human Predicates in Generated Query APIs
Generated query APIs contain language, not only identifiers. That makes a small grammatical choice part of the public contract.
For a collection of people, TeaQL uses whoAreActive(), not whoIsActive(). For an ordinary human
attribute it uses whoseEmailIs(...). A non-human entity uses whichAreActive() and
withCodeIs(...).
These forms sound related, but they solve different problems: whose expresses possession, while
who are agrees with the plural result set.
Humanity must be declared
TeaQL classifies an entity as human only when the model explicitly declares cat="human". The
generator does not infer it from names such as customer, user, employee or person.
This avoids cultural guesses and domain ambiguity. A user may be a service account; a customer
may be an organization. The model owns the semantic decision.
One vocabulary, six casing conventions
Java generated Request APIs are the semantic gold standard. Other languages preserve the same meaning and adapt casing only:
| Predicate | Human | Non-human |
|---|---|---|
| scalar field | whose<Field>... | with<Field>... |
| positive boolean | whoAre<Field> | whichAre<Field> |
| negative boolean | whoAreNot<Field> | whichAreNot<Field> |
Boolean fields should preferably be adjectives such as active. A field named is_active pushes
grammar into schema naming and tends to generate repeated Is fragments.
Why this needed a generator-level test
Several target templates once hard-coded with, bypassing the human classification. Java also had
a remaining singular boolean form. Fixing examples would not have fixed generated APIs.
We centralized predicate naming and added paired fixtures: a human person and a non-human
device, both with equivalent string, scalar and boolean fields. The six-language test requires
forms equivalent to whoseEmailIs, withCodeIs, whoAreActive, whoAreNotActive and
whichAreActive, while rejecting whoIsActive.
The lasting rule is simple: semantic vocabulary comes from the model and generator core, never from a target template's intuition.