JFaster Language Specification

Version 1.0 draft — 2026-09. This document defines the JFaster modeling language: its compact syntax, its constructs and their meaning. It is independent of any implementation. A JFaster implementation reads a model written in this language and produces a working application from it.

1. Overview

A JFaster model describes a data-centric business application: the entities it manages, their properties and relationships, named queries (subsets), search filters, list views (listings), operations (actions) and rules to prefill records (defaultsets).

The model is the single source of truth. Storage, business services, the API, forms and listings are all derived from it, so they cannot disagree with each other. A field is declared once.

The language has two notations that are used together:

A model can be split into several source files (for example one per module: Sales.txt, HR.txt). Together they form a single model: an entity in one file can reference an entity in another.

1.1 A first model

## Customers and their orders
Customer @Sales order="name"
   name d r
   email
   country Country

Order @Sales order="orderDate desc"
   customer Customer d r
   orderDate date ds r default="now"
   lines OrderLine set ei x childproperty="order"

OrderLine @
   order Order
   product Product r
   quantity integer r

Product @Catalog order="name"
   name d r
   price double r

Country @Configuration order="name"
   name d r

This model defines five entities, their fields and relationships, an order with editable lines, and a menu with three groups. Nothing else is needed for a working application.

2. Lexical structure

A source file is read line by line. Leading and trailing whitespace does not matter, so indentation is not significant: indenting properties under their entity is a readability convention. Empty lines are ignored.

2.1 Kinds of lines

Rules:

• Comments occupy a whole line and start with ##. There are no end-of-line comments.
• Every line of embedded XML starts with <. Write one tag per line and never split a tag across lines. Nested elements go on their own lines.
• Entity and property lines are told apart by the case of their first letter, not by indentation.

2.2 Tokens

Entity and property lines are split into tokens separated by spaces.

• A double-quoted string is one token, even with spaces inside: "Grand total".
• A token of the form key="value" is an attribute.
• Everything else is a keyword or a name, as described in §3 and §4.

3. Entities

3.1 Entity line

Name [@Menu_Group] [&Entity_Label] [transient] [key="value" ...]

Menu and label are always written with @ and &, never as menu="..." or label="..." attributes.

Every line after an entity line, up to the next entity line, belongs to that entity: its properties, tabs and embedded XML.

3.2 Persistent and transient entities

• A persistent entity (the default) is stored data. It has records that can be created, listed, searched, edited and removed. Name it with a singular noun: Invoice, Customer, Enrollment.
• A transient entity is an operation: a form that performs something when submitted (approve, import, send, close a period, run a batch process). Its data is not stored. Name it with a verb: ApproveInvoice, ImportPrices, SendReminder. It is usually opened from an action (§6.4) and prefilled with a defaultset (§6.5).

3.3 Entity attributes

4. Properties

4.1 Property line

name [type] [EntityName] [modifiers...] ["Label"] [key="value" ...] [\]

The first token is the property name, in camelCase. The other tokens can appear in any order:

Labels are always written as a quoted token (total double "Grand total"), never as label="...".

A line can declare several properties separated by / (a slash with spaces around it):

firstName d r / lastName d r / email

4.2 Types

Name as type. When the property name is itself a type keyword, the property has that type:

email r
date "Due_date"
file "Attachment"

declare a required email, a date labeled "Due date" and a file. In that case do not repeat the type (write email r, not email email r). Otherwise, give the property a descriptive name and its type: issueDate date, workEmail email.

Avoid naming a property like a modifier (hidden, fixed, list, set, d, r, x).

4.3 Relationships and collections

Collections: set (no duplicates, no particular order), list (ordered; listindex="field" stores the position), sortedset (kept sorted by sortexpr="expression").

Inline detail or embedded listing. Use set ei x for a few rows that are part of the parent (invoice lines, addresses, schedule items). For many records, or records with their own life (payments, messages, history), use an embedded listing (§6.6).

4.4 Enumerations

An enumeration is declared once, usually at the top of the file, and referenced by name:

<enumset name="Priority">
<enum value="low">Low</enum>
<enum value="high">High</enum>
</enumset>

Task @Tasks order="title"
   title d r
   priority enum enumset="Priority" default="low"
   labels set enum enumset="Label"

value is what is stored; the element text is what users see.

4.5 Continuation (\)

A property line that ends with \ is followed by embedded XML that belongs to the property: its own actions, an inline enumeration or a dynamic value (§6.7). The property ends at the next property, entity or tab line.

customer Customer d \
   <action name="viewCustomer" type="openentity" label="View" />
unitPrice double disabled \
   <dynamicvalue expr="product.price">
   <param name="product" entity="Product" value="product" />
   </dynamicvalue>
quantity integer r

4.6 Property attributes

5. Tabs

Long forms are divided into tabs. A #tab line starts a tab that lasts until the next #tab line or the end of the entity.

Employee @HR order="lastName"
   #tab Personal
   firstName d r / lastName d r
   birthDate date
   #tab "Job_details"
   department Department r
   startDate date

#tab Word uses the word as label; #tab "Two_words" uses the quoted label with underscores as spaces.

6. Behavior

These constructs are written as embedded XML inside an entity.

6.1 Subsets: named queries

A subset is a named query over the entity's records, optionally with parameters. It is defined once and reused by selectors, listing tabs, embedded listings and filters.

Province @Configuration order="name"
   <subset name="forCountry" order="name">
   <param name="country" entity="Country" />
   <condition field="country" value="country" />
   </subset>
   name d r
   country Country r

Address @
   country Country r
   province Province subset="forCountry" subsetparams="country"

Write the parameters first, then the conditions, then the restrictions. Give every subset an order. Express queries in the model rather than in code.

6.2 Filters

A filter is a search field on the listing.

<filter name="status" property="status" display="primary" />
<filter name="search" label="Search" display="primary">
<or>
<condition field="name" like="concat('%', search, '%')" />
<condition field="code" like="concat('%', search, '%')" />
</or>
</filter>

A filter either searches one property (property="...") or defines its own conditions, where the filter's name is the value typed by the user. display="primary" shows it by default; display="secondary" shows it among the advanced filters.

6.3 Listings and tabs

A listing is a view of the entity's records. Tabs split it by subset, each with its own actions:

<listing name="main">
<tab name="open" label="Open" subset="open" displayactions="assign,close" />
<tab name="closed" label="Closed" subset="closed" displayactions="reopen" />
</listing>

An entity can have several listings (per role or context). displayfilters, displayactions and displayproperties choose what a listing or tab shows.

6.4 Actions

An action is a button that starts something from a form or a listing.

<action name="approve" label="Approve" type="relatedentity" entity="ApproveExpense" location="local" defaultset="forExpense" />

6.5 Defaultsets

A defaultset prefills a new record from a context: a parameter goes in, fields come out.

ApproveExpense @ transient
   <defaultset name="forExpense">
   <param name="expense" entity="Expense" />
   <default name="expense" value="expense" />
   <default name="approver" value="User:find(userId)" />
   </defaultset>
   expense Expense fixed
   approver User fixed
   notes text

For batch actions the parameter is a collection of the selected records:

<param name="expenses" entity="Expense" collection="set" />

6.6 Embedded listings

An embedded listing shows the related records of another entity inside a form.

Company @CRM order="name"
   name d r
   <embeddedlisting name="employees" entity="Person" subset="forCompany" subsetparams="." defaultset="newForCompany" defaultsetparams="." />

subsetparams="." passes the current record. The defaultset prefills records created from the embedded listing.

6.7 Dynamic values

A dynamic value computes a field from related data whenever its parameters change:

unitPrice double disabled \
   <dynamicvalue expr="product.price">
   <param name="product" entity="Product" value="product" />
   </dynamicvalue>

Use it when the value comes from other records (product.price). Use calculated (§7.1) when it only depends on fields of the same form.

7. Expressions

A model uses three expression languages. Each attribute uses exactly one of them.

7.1 Form expressions

• A field is referenced by name: status. Paths go through references: customer.active.
• . is the current record.
• Strings go in single quotes: status = 'approved'.
• Comparison: =, !=, <, >, <=, >=. Logic: and, or, not(...).
• Arithmetic: +, -, *, div, mod. Division is div, because / separates path steps.
• Aggregates over detail rows: sum(lines[*].amount).

discount double displayif="customer.vip = 'true'"
subtotal double calculated="sum(lines[*].amount)"
tax double calculated="subtotal * (taxRate div 100)"

In production models, equality with a string literal is by far the most common condition, and sum(collection[*].field) accounts for one in four calculated fields.

7.2 Server expressions

Navigation through references (invoice.customer.email), finders (User:find(userId), Status:findOneBy('code', 'OPEN')), now and userId, the id of the logged-in user. userId refers to the model's own User entity: every model that uses it declares a User entity. Method calls on values (list.size()) are not part of the language.

7.3 Query expressions

formula is a SQL expression evaluated for each record, for example (SELECT COUNT(*) FROM person WHERE person.company = id). A <restriction> expression is a query predicate where me is the current record and each ? is bound to a <param>.

8. Meaning of a model

A JFaster implementation derives the whole application from the model:

• Each persistent entity gets storage, a form to create and edit records, a listing with its filters, tabs and actions, and an API to read and write records.
• Each transient entity gets a form and an operation that runs when the form is submitted.
• Subsets are available wherever records are chosen, listed or queried, including the API.
• Menus group the entities by their @ group.
• Business rules that the model cannot express (complex validations, integrations, calculations) are written as code in the implementation's extension points. They complement the model; they never duplicate what the model declares.

9. Style rules

1. Every entity has order="..." and at least one d property.
2. Persistent entities are singular nouns; transient entities are verbs. Name relationship entities by their meaning (Enrollment, not StudentCourse).
3. Don't prefix entity names with the owner (Category, not ProductCategory) unless there is ambiguity.
4. Comments are ## lines. XML is one tag per line.
5. Labels are quoted tokens, menus are @Group, entity labels are &Label.
6. Queries go in subsets, not in code. Subsets declare an order.
7. Operations are transient entities opened by actions and prefilled by defaultsets.
8. Prefer inline detail (set ei x) for a few owned rows and embedded listings for many or independent records.

10. Usage in production

The language has been used for about 20 years to build business systems. The figures below come from 196 production models across about 75 projects.

Production systems written in the language reach 100 to 500 entities and hundreds of actions.

Appendix A. Complete example

<enumset name="ExpenseStatus">
<enum value="draft">Draft</enum>
<enum value="submitted">Submitted</enum>
<enum value="approved">Approved</enum>
</enumset>

## People
Employee @Staff order="lastName"
   firstName d r / lastName d r
   workEmail email r
   department Department

Department @Staff order="name"
   name d r

## Expense reports and their approval
ExpenseReport @Expenses order="submittedOn desc"
   <subset name="submitted" order="submittedOn desc">
   <condition field="status" value="'submitted'" />
   </subset>
   <listing name="main">
   <tab name="all" label="All" />
   <tab name="toApprove" label="To approve" subset="submitted" displayactions="approve" />
   </listing>
   <filter name="employee" property="employee" display="primary" />
   <filter name="status" property="status" display="primary" />
   <action name="approve" label="Approve" type="relatedentity" entity="ApproveExpenseReport" location="local" defaultset="forReport" />
   employee Employee d r
   submittedOn date ds r default="now"
   purpose d r
   lines ExpenseLine set ei x childproperty="report"
   total double ds calculated="sum(lines[*].amount)"
   status enum enumset="ExpenseStatus" default="draft" fixed

ExpenseLine @
   report ExpenseReport
   date r
   concept d r
   amount double r
   receipt image

ApproveExpenseReport @ transient
   <defaultset name="forReport">
   <param name="report" entity="ExpenseReport" />
   <default name="report" value="report" />
   </defaultset>
   report ExpenseReport fixed
   notes text