Tweaks you can make in Jargon to make your Domains clearer
Jargon is an opinionated platform for designing APIs and Data Models based on principles from Domain Driven Design. These opinions help to make modelling Domains quick and simple, and will result in pretty good outcomes.
No predefined set of opinions will be perfect for all situations, so Jargon offers a number of tweaks you can change to make the intent of your Domains clearer for people to understand — which is Jargon’s mission.
There are two main mechanisms to apply tweaks:
Processing Instructions, which are inserted into the text of the model and generally change aspects of the generated Domain Model
Key-Value Pairs, which are added to data definitions of Classes and Properties and generally* change how Jargon interprets them.
- There are some Key-Value Pairs that change the Domain Model diagram that don’t really work as Processing Instructions — but we’ll cover them below.
Processing Instructions
Processing instructions look a lot like members, but they all start with a #. Jargon will give you a list of matching options and a brief description to help you choose (or remember!) which one you’re interested in.
The full list is available in the Jargon Docs, but we’ll go over the ones that Jargon supports at the time of writing.
#important
Highlights a class to make it more important than others. It’s really only a visual aid for consumers to help their eyes be drawn to the parts you think are the most important.
#additionalRows:n
Jargon calculates the width and height of Classes to fit their contents. You can increase the vertical length of a class by adding space below the last Property.
#shortImports
Importing Classes and Properties from other Domains is a common occurrence in Jargon, however this can lead to quite wide Classes to accomodate the entire import path. #shortImports shortens them to just the name of the Property:
#hideClass
Sometimes Classes are mechanically required, but don’t really do much to help someone understand the Domain. Make your Domain clearer to understand by hiding them — they’re still in the Domain, just not on the diagram.
#localSupers
When a Class has a SuperClass, it inherits all its Properties. When the SuperClass is in another Domain, Jargon will list all the inherited Properties in the Diagram. When the SuperClass is in the same Domain, Jargon doesn’t — unless you use the #localSupers Processing Instruction.
#noRoutes
Like #hideClass, there are circumstances when having a Class on the Diagram doesn’t help people understand the Domain, however you may still want to show people that there is indeed a Class. #noRoutes removes all routes to and from a Class. Useful for Composite Datatypes.
#group:name
There may be situations where you want to group multiple Classes together within the same Domain. You can use #group:name to do that. Be careful with this one — if you have Classes that do share some relationship that is important enough to group, there’s a good chance you’ve discovered a new Domain which should be extracted.
Key-Value Pairs
Key-Value Pairs are included within the definition of a Property or Class, and all have this pattern: [group.key]=value. The up-to-date list of the ones that Jargon recognises is in the Jargon Docs, but we’ll go over all the ones that are supported right now.
[jargon.aggregation], [jargon.reference], [jargon.aggregation], [jargon.deprecated]
These all impact how Jargon interprets the modelling of the Classes that use them. Take a look at the in-depth article that covers them all.
[jargon.required]=true
Makes this Property required. This will flow through to JSONSchema and OpenAPI Specifications.
[jargon.jsonSchemaRoot]=true
Generates this Class as a JSONSchema. See the detailed JSONSchema guide.
[jargon.hideRoute]=true
Like the #noRoutes Processing Instruction, there may be times when you want to hide routes between Classes. Unlike #noRoutes, [jargon.hideRoute]=true lets you select specific routes to hide.
[jargon.routeX]=x, [jargon.routeY]=y
Jargon tries hard to layout your Domains in an intelligent way — but it doesn’t always get it right. You can use these Key-Value Pairs to tweak the positions of the routes between Classes:
[jargon.extraEnums]=x,y,z
If you’re using an imported code table from another Domain, but really, really, really need to add one or two extra enumerations, this will do that for you. It’s really only meant for mechanical values, such as ‘None’, or ‘n/a’.
[oas.mediaType]=multipart/form-data
In an OpenAPI Spec, Jargon will set the media type to ‘application/json’, to indicate that your API will accept a JSON encoded version of the Class. If your API needs a different encoding, this will change the media type for a Class, when it’s in the body of a request.
[oas.exclusiveMaximum]=5
Adds ‘exclusiveMaximum=5’ to this property in an OpenAPI specification, which limits the number of items in an array to a maximum of 5.
[oas.exclusiveMinimium]=5
Adds ‘exclusiveMinimium=5’ to this property in an OpenAPI specification, which limits the number of items in an array to a minimum of 5.
[oas.pathName]=newPathChunk
Jargon will infer the API paths for you, based on the names of your classes and some rules for pluralisation. If Jargon’s got it wrong for a particular Class, you can override it with this.
[oas.readOnly]=true
Adds the ‘readOnly=true’ to this property in an OpenAPI specification, indicating that the Client cannot send this Property to the Server.
[oas.writeOnly]=true
Adds the ‘writeOnly=true’ to this property in an OpenAPI specification, indicating that the Server will not send this Property to the Client.
[oas.queryParamName]=x
Jargon allows you to define query parameters in API paths based on Properties from the Domain. It will use the name of the Property for the query parameter. If that’s not what you want, this will set the name of the query parameter, but still get the type and description from the Property.
[oas.compoundKeyName]=x
Jargon allows Classes to have multiple keys, which will then flow through to API pahts. Jargon will come up with a valid, but rather ugly, name for these path paramaters. If a Class has multople keys, you can change their generated path parameter with this.
[oas.securityScopeAcronym]=xx
Jargon can create security scopes for APIs, and this allows you to specify an acronym for a Class to use when creating the scopes.
[oas.codeColumn]=name
Jargon will default to using the first column of a code table to create the values for an OpenAPI specification’s enumeration. This will let you choose the name of the column to use instead.
[oas.x-enum-descriptions]=name
OpenAPI enumerations are a simple array of values, which isn’t always very useful for code generators. You can use this to select the name of a column in the code table, and Jargon will add them with the x-enum-descriptions property (a non-standard but widespread way to give the OpenAPI enumeration values more friendly names)
Wrapping up:
So that’s a pretty exhaustive overview of the tweaks that Jargon supports to help you clearly describe your Domain to others.
If you have any further questions about Processing Instructions or Key-Value Pairs, 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.
