Creating JSONSchema with Jargon

Jargon can export select Classes from your Domain as JSONSchema, which you can then import into downstream tools or integrate into your development processes.

Let’s take a look at how to do it:

Jargon forces separation between the structure of your Domain (the textual representation of your model) from its business definitions and annotations. Everything that’s not in the model text (such as specifying which class becomes a JSONSchema) is specified via the business definition pane.

Here’s an example:

The definition pane is where the business definition of Classes and Properties is specified, along with key-value pair annotations that modify how Jargon processes things.

There’s a textual business definition, and below that a key-value pair (with the key in the square brackets [], then an equals sign, then the value). This particular example tells Jargon that this class is abstract — which is covered in our article on advanced API and data modelling.

The list of key-value pairs that Jargon recognises is listed in the Jargon documentation, but I’ve listed a few here to give you an idea of what they can do:

• [jargon.required]=true — Makes this property required. Also adds the ‘required=true’ to this property in an OpenAPI specification
• [jargon.deprecated]=true — Marks this property as deprecated, flagging that it may be removed in the future
• [jargon.extraEnums]=x,y,z — Adds extra enumeration values to this usage of a CodeTable. Useful when you are using an imported CodeTable, and you need to add some mechanical values, such as ‘None’, or ‘n/a’
• [jargon.jsonSchemaRoot]=true — Exports this Class and all its dependencies as a JSONSchema file

The last one [jargon.jsonSchemaRoot]=true is the key-value pair that triggers Jargon to export a class as a JSONSchema file:

Adding [jargon.jsonSchemaRoot]=true to the definition of a Class will export that class as a JSONSchema file

After you save the Domain, you will find links to the JSONSchemas in the Domain’s artefacts tab:

The Exported JSONSchema files are listed with the rest of the raw artefacts, at the bottom of the artefacts tab

Each time you save the Domain, Jargon will re-export the JSONSchema files, ensuring that they are always up-to-date with your Domain.

JSONSchema files can only have a single root Class

Let’s take a quick look at the two JSONSchema files that I’ve created for this article: Customer and Store.

The Domain used for this example. Order and Customer. The Order class does not have a reference to the Customer Class — so it won’t be included in its JSONSchema

The Exported Customer JSONSchema looks a little like this. Notice that it has a $defs entry for each of the Classes that Customer is dependant on:

The JSONSchema for the Customer Class

The Exported Store JSCONSchema has a corresponding $defs entry, but it only contains the Classes that Store depends on:

The JSONSchema for the Store Class

If your Domain isn’t a tree structure, and doesn’t have a natural root, you can create an artificial one if you desperately need to have a single JSONSchema file with all of the Classes in your Domain in it.

That would look something like this (the name of the Class doesn’t matter — you don’t need to name it JSONSchemRoot):

An artificial JSONSchemaRoot Class, that only exists to export a JSONSchema file that contains all the disparate root Classes in your Domain

That’s now a little bit confusing though, and can get quite messy if you have a large number of disparate roots that you want to include.

Fortunately, Jargon supports processing instructions that you can use to alter the presentation of the Domain Model in the diagram, and one in particular is perfect for this situation:

• #hideClass — removes this class from the diagram. Useful for any mechanical classes that don’t add to the understanding of the Domain

Adding the #hideClass processing instruction to the JSONSChemaRoot class hides that Class and all connections from the diagram:

How the #hideClass processing instruction looks

The Domain, with the hidden JSONSchemaRoot class

The JSONSchema for the JSONSchemaRoot Class looks something like this, and contains all the Domains’ Classes within the $defs entry:

The JSONSchema for the JSONSchemaRoot Class

Wrapping up:

So that’s how you can export some or all of your Domain’s classes as JSONSchema files.

Jargon manages JSONSchemas alongside all other derivitive views of your Domain: as artefacts. This has a couple of important benefits:

• it keeps them all together in one place,
• it ensures that they are always kept up-to-date,
• they are versioned alongside the Domain,
• they are included in webhooks that Jargon can emit when a Domain is released, or has a snapshot taken.

The Domain Model for this article is available in the public Jargon instance.

If you have any further questions about JSONSchema, key-value pairs or processing instructions, you can:

• check the Getting Started Guide
• leave a comment below
• raise an issue at the jargon issue tracker GitHub repository
• Sign up for a free Jargon account and try some out for yourself.