Introducing Jargon — Modelling Data

5 min readJun 22, 2021

Ok, so I’ve created a Domain — now what?

If you’ve been following along in this series, you should now know what a Domain is in Jargon, and how how to create and save them.

This article will go over the mechanics of modelling a Domain in Jargon.

Data Models as Code

In Jargon, you create your models as code — a textual description of the Classes and Properties within your Domain.

Don’t be afraid if you have no experience writing code — Jargon is very quick and simple to understand.

Don’t let the fact that Jargon uses code to model put you off, Jargon is still a very visual tool for modelling and will instantly adapt it’s diagram view as you type.

Here’s an example of how quickly that works:

Every time you press a key, Jargon will update the diagram to reflect your changes

Even though it’s code-based, Jargon still lets you control the structure and layout of your diagrams. As you click and drag a Class around, Jargon will attempt to reposition and route the connections, making it easy to tell what Classes are connected together.

Either move individual Classes, or select mlultiple to move them around

The Jargon Language

There’s a full reference of how the language works in our Getting Started Guide, and I highly encourage you to take a look. In the Guide, there are samples that have syntax highlighting like Jargon does, and you can copy and paste them into your own Domains to see how they work.

If reading the Guide isn’t for you, here are the main features that you will need to create your own Domains.

A simple example

Here is a Domain with only two Classes: Driver and Car.
Drivers have an Id and are assigned a Car, which has a registration number.

Driver
 ^id:Text
 assignedCar:CarCar
 registration:Text

It looks like this in Jargon:

Jargon links Classes together when one Class has another as a Property

You create a new class by typing it’s name on a new line, without any whitespace or indentation.

Car

You add a Property to a class by typing it’s name and type on a new line under a Class, with at least one space of indentation. The name of the property comes first, then a colon character ‘:’ then the type.

Car
 registration:Text

Jargon recognises these built-in primitive types:

'Numeric' - for any type of number'Text' - for any type of text string'Indicator' - for true or false'Date' - for dates'Code' - for an enumerated set of values (more on them in later articles)

A Class can have an array of a property, by placing [] after the Property’s Type:

Person
 luckyNumbers:Numeric[]

Properties can also use Classes as their type, by using the name of the Class:

Driver
 assignedCar:Car

You can also create a reflexive Property, which is a property that is the same type of it’s owning Class:

Person
 parent:Person

You can also create a SubClass — a Class that inherits all the Properties of it’s parent, by typing the name of the SubClass, then a colon ‘:’ then the name of the parent Class:

Vehicle
 name:TextCar:Vehicle
 numberOfDoors:Numeric

As you type each of these, Jargon will offer intelligent suggestions of what is available, which makes it easier to model things quickly:

Context-aware auto-complete options are provided to help you quickly model your Domain

Colours in Jargon have meaning

A Domain in Jargon doesn’t just model the structure of the data, but also how that data is Addressed and accessed — which is a common problem in Software Engineering.

Jargon is inspired by a popular solution to this problem, called Domain-Driven-Design, and shares many of the same concepts.

There are three types of Class in Jargon, each with a different approach to how instances of that Class are Addressed.

Example

Entity
 ^identifIier:Text
 values:ValueObject[]ValueObject
 notAnIdentifier:TextAggregate
 getsIdentifiersFrom:Entity

Entity

An Entity is a Class that has Identifiers, and is represented by the colour Blue.

PlayingCard
 ^value:Numeric
 ^suit:Code(Suits)

If you had a deck of playing cards, you can Address every single card in the deck with the combination of it’s value and suit, eg: the 6 of Hearts.

Jargon will automatically classify your Classes into the relevant type, based on a Class’s properties that are Identifiers. You can make a Property into and Identifier, by starting it’s name with a caret ‘^’.

Here’s how that looks:

ValueObject

A ValueObject is a Class that has no Identifiers, and is represented by the colour Green.

There is no way to uniquely address a ValueObject.

Whenever you access an Entity, it has access to all of it’s ValueObjects.

BankAccount
 ^number:Numeric
 transatctions:Transaction[]Transaction
 value:Numeric

Aggregate

An Aggregate is a Class that has no Identifiers of it’s own and derrives it’s business-identity from it’s child Properties, and is represented by the colour Pink.

Transaction
 value:Numeric
 log:LogEntryLogEntry
 ^timestamp:Text
 ^id:Text

Wrapping up

This wraps up the major components of the Jargon language, and should be enough for you to start creating your own Domains.

check the Getting Started Guide
leave a comment below
raise an issue at the jargon issue tracker GitHub repository