Introducing Jargon — Modelling Data

Alastair Parker
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:Car
Car
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:Text
Car: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:Text
Aggregate
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:LogEntry
LogEntry
^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.

--

--

Alastair Parker

Semantic data nerd, and creator of https://Jargon.sh - a collaborative platform for developing data models and vocabularies