JoinedWorkz
Docs1.3.80

Appearance

DSL overview ​

JoinedWorkz uses a small family of domain-specific languages (DSLs) to describe models and platforms in a consistent way.

This page gives you the big picture and points you to the detailed references.

  • CMN – Canonical Model Notation (.cmn) Describes your domain model and APIs: types, services, resources, components, applications.
  • Profile DSL (.profile) Describes platforms and how generators interpret the canonical model: stereotypes, properties, outlets, cartridges, platforms.

For detailed syntax see:

1. Mental model ​

You can think of the DSLs like this:

  • CMN (.cmn) – what your system looks like: domain concepts, operations, APIs, components and applications.
  • Profiles (.profile) – how this model is interpreted for a specific technology stack (Base, Java, Spring Boot, …).
  • Facilities – Maven modules that bundle profiles, base CMN models, cartridges and generators for one or more platforms.

A typical setup looks like this:

  1. Your project adds one or more facilities as Maven dependencies (for example the Base facility, Java facility, Spring Boot facility).
  2. Those facilities contribute:
    • profile files (.profile) with stereotypes, properties, outlets, cartridges, and platforms,
    • CMN models with shared types (base types, method types, …),
    • generator and cartridge implementations.
  3. Your CMN models (.cmn) import the shared CMN models and bind to a platform from one of the profiles via the platform header.

2. Typical file locations in a project ​

In a JoinedWorkz-based project you usually see the following files:

  • model/**/*.cmn Your canonical models: domain types, APIs, components, applications.
  • joinedworkz.properties Project-level configuration for outlets and other overrides (for example to route generated Java sources into specific modules). In release 1.3.80, keep the file present even when empty for SpringBoot projects; missing and empty are not yet equivalent.

Profiles (.profile) and shared CMN models for base types or method types live in facilities. Your model imports the CMN packages it uses and selects the facility-provided profile platform separately:

cmn
package com.example.app

import org.joinedworkz.facilities.common.base
import org.joinedworkz.facilities.common.base.api

platform Base

You normally do not edit the profile files from facilities. The platform Base header selects the profile platform; it is not a CMN package import. You can optionally override documented properties such as outlet directories via joinedworkz.properties.

3. End-to-end workflow ​

At a high level, working with the JoinedWorkz DSLs looks like this:

  1. Choose facilities and platforms

    • Add the required facilities as Maven dependencies (for example the Base facility and a platform-specific facility such as Java or Spring Boot).
    • Decide which platform(s) your CMN models should target.

  2. Model your domain in CMN

    • Define simple and complex types, enums and services.
    • Describe APIs with resources and method types.
    • Group endpoints into components and assemble them into applications.

  3. Bind to a platform

    • In each CMN file, select the platform in the header:
      cmn
      platform Base
    • Optionally disable specific cartridges for a model:
      cmn
      platform SpringBoot exclude DtoCartridge

  4. Generate artifacts

    • Run the Maven build (JoinedWorkz generator plugin) or
    • use JoinedWorkz Studio for interactive validation and generation while editing the model.

  5. Iterate

    • Refine the CMN model and re-generate.
    • If needed, extend or customise platforms and cartridges in facilities (usually in separate modules).

4. Where to go next ​

Use the following pages depending on what you want to do: