DEV Community

Cover image for FlowScript 0.1: A semantic language for describing applications before implementation
Erland Kjensli
Erland Kjensli

Posted on

FlowScript 0.1: A semantic language for describing applications before implementation

#showdev #opensource #architecture #programming

I've been exploring a question that sits somewhere between software architecture, DSL design, application modeling, UX structure, and programming-language design:

Can we describe the semantic model of an application in a compact, human-readable notation before implementation begins?

That experiment is now public as FlowScript 0.1.

GitHub repository:

https://github.com/erlandkjensli-hue/FlowScript

The current release is an experimental working draft:

https://github.com/erlandkjensli-hue/FlowScript/releases/tag/v0.1.0

From flowcharts to application semantics

The idea started from a familiar problem.

Flowcharts are useful for showing sequences, decisions, and transitions. But modern applications contain much more than a sequence of boxes and arrows.

An application also has:

  • structure and hierarchy
  • logical destinations
  • UI structure
  • navigation
  • user interactions
  • actions and side effects
  • conditions
  • state
  • context and dataflow
  • validation
  • asynchronous behavior
  • errors and feedback
  • reusable structures
  • responsive presentation

Trying to represent all of this as a traditional flowchart quickly becomes awkward.

That led to a different question:

What if the diagram is only one possible projection of a more fundamental application model?

FlowScript explores that idea.

The central idea

The current proposal is that FlowScript should describe the semantic model of an application, rather than its implementation.

In other words:

Describe what the application is and how it behaves before deciding how it is implemented.

A FlowScript document should ideally remain meaningful if the implementation changes.

It should not need to know whether the eventual application uses React, another UI framework, a particular backend, a particular database, or a particular deployment architecture.

The implementation is downstream.

Structure is not navigation

One of the first problems that appears in application modeling is that hierarchy and navigation are easy to confuse.

Suppose we have:

page:LIST
    list:ITEMS
        item:ITEM
Enter fullscreen mode Exit fullscreen mode

This tells us something about structure.

It does not necessarily tell us that the user can navigate from LIST to ITEM.

That relationship should be explicit:

page:LIST
    list:ITEMS
        item:ITEM
            goto:DETAIL

page:DETAIL
Enter fullscreen mode Exit fullscreen mode

This distinction may seem small, but it matters because hidden inference makes models ambiguous.

FlowScript currently treats the structural tree and the navigation graph as related but separate concepts.

Structure, navigation, and state are different graphs

A mature FlowScript document will probably contain multiple overlapping structures rather than one universal graph.

At minimum:

Structural tree

What contains what.

LIST
└── ITEMS
    └── ITEM
Enter fullscreen mode Exit fullscreen mode

Navigation graph

What can lead to what.

LIST → DETAIL
DETAIL → LIST
Enter fullscreen mode Exit fullscreen mode

State graph

How state changes.

ACTIVE → ARCHIVED
Enter fullscreen mode Exit fullscreen mode

These relationships may refer to the same semantic objects, but they answer different questions.

That separation is one of the core ideas being tested in 0.1.

Structure is not presentation either

Another important distinction is between the logical application model and the way that model is presented on a device or viewport.

For example, the same logical destination might appear as a complete page on a compact layout and as a pane alongside other content on a larger layout.

The semantic identity should remain the same.

Conceptually:

page:DETAIL
Enter fullscreen mode Exit fullscreen mode

could be presented as:

compact
    DETAIL

regular
    LIST | DETAIL

expanded
    NAVIGATION | LIST | DETAIL
Enter fullscreen mode Exit fullscreen mode

The presentation changes.

The application model does not.

This leads to a broader hypothesis:

Responsive UI can be treated as a projection of the semantic model rather than a collection of separate application hierarchies.

Actions are not navigation

Another distinction is between what the user does and what the system does.

For example:

button:"Save"
    action:SAVE
    goto:HOME
Enter fullscreen mode Exit fullscreen mode

There are two different semantic events here.

The user interacts with a control.

The system performs an action.

Then the navigation context changes.

Keeping those concepts separate makes behavior easier to reason about and potentially easier to reuse.

Conditions are not state

FlowScript also explores a strict distinction between conditions and state.

A condition asks:

Is this predicate true?

For example:

condition:USER_AUTHENTICATED
Enter fullscreen mode Exit fullscreen mode

State asks:

What state is this object or process in?

For example:

state:LOADING
state:ERROR
state:ACTIVE
state:ARCHIVED
Enter fullscreen mode Exit fullscreen mode

The distinction becomes important when models become more complex.

A state machine, a boolean predicate, a visibility condition, and a permission rule may all affect what the user sees, but they are not necessarily the same semantic thing.

A deliberately small syntax

One design goal is to keep the written notation simple.

The current direction is roughly:

keyword:value
Enter fullscreen mode Exit fullscreen mode

with indentation expressing semantic nesting.

For example:

page:DETAIL
    heading:"Detail"

    field:VALUE

    button:"Save"
        action:SAVE
        goto:HOME
Enter fullscreen mode Exit fullscreen mode

The syntax is intentionally lightweight.

The underlying semantics should be much stricter than the notation looks.

That gives us an important design principle:

Syntactic simplicity, semantic strictness.

A future parser should be able to validate references, nesting, targets, conditions, state declarations, and other relationships even though the source remains relatively easy to read and write.

What FlowScript is not

FlowScript is not intended to replace programming languages.

It is not intended to replace:

  • TypeScript
  • JavaScript
  • HTML
  • CSS
  • backend code
  • API schemas
  • database schemas
  • visual design tools

The idea is to operate at a different level.

A FlowScript document could describe the semantic structure and behavior of an application, while implementation technologies determine how that model becomes software.

The possible long-term direction

There is a larger hypothesis behind the project.

If a semantic application model can be expressed rigorously enough, the same source could potentially support multiple projections.

For example:

FlowScript
   ├── hierarchy diagram
   ├── navigation graph
   ├── state diagram
   ├── responsive presentation map
   ├── documentation
   ├── test cases
   └── eventually implementation scaffolding
Enter fullscreen mode Exit fullscreen mode

That is not what FlowScript 0.1 does.

It is a direction that becomes interesting only if the underlying semantic model turns out to be useful.

Why release it this early?

Because the hardest part is probably not the syntax.

The difficult questions are semantic.

Which concepts are actually fundamental?

Which concepts overlap?

Which distinctions are necessary?

Which concepts are too specific to one kind of application?

What is missing?

What should never belong in the language?

Those questions are difficult to answer in isolation.

So FlowScript 0.1 is being published as an experimental working draft, specifically so that other people can challenge the model.

What I am looking for

The most useful feedback at this stage is not:

"I would write this syntax differently."

Syntax can change.

More useful questions are:

  • Does the semantic distinction make sense?
  • Is a concept actually general?
  • Is something being modeled at the wrong level?
  • Are two concepts actually the same thing?
  • Is an important semantic category missing?
  • Can the same model describe very different applications?
  • Could two different implementations use the same FlowScript description?

Concrete examples and counterexamples are particularly useful.

The current development order

The project deliberately follows this order:

concepts
   ↓
semantic model
   ↓
vocabulary
   ↓
syntax
   ↓
grammar
   ↓
validation
   ↓
tooling
Enter fullscreen mode Exit fullscreen mode

The reason is simple.

If grammar is frozen too early, it can make the language look precise before the underlying model is actually understood.

FlowScript 0.1 is therefore more interested in semantic review than syntax freeze.

Where the project is now

The first public draft is available on GitHub:

https://github.com/erlandkjensli-hue/FlowScript

The specification is here:

https://github.com/erlandkjensli-hue/FlowScript/blob/main/docs/FLOWSCRIPT-0.1-DRAFT-SPECIFICATION-2026-09-18.md

The roadmap is here:

https://github.com/erlandkjensli-hue/FlowScript/blob/main/ROADMAP.md

The current release is:

https://github.com/erlandkjensli-hue/FlowScript/releases/tag/v0.1.0

The project is intentionally open to discussion, criticism, examples, alternative models, and independent implementations.

The main question

For me, the central experiment is this:

Can a person who has never seen the implementation understand the application's architecture and behavior from the FlowScript model alone?

And an even stronger test:

Can two different implementations of the same application be described by the same FlowScript?

If the answer eventually turns out to be yes, FlowScript may be doing something more interesting than drawing flowcharts.

If the answer is no, the experiment should tell us why.

That is what I would like to find out.

I'd particularly like feedback from people interested in programming-language design, DSLs, software architecture, application modeling, and developer tooling.

Top comments (0)