JoinedWorkz

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 (.profil)
    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 (.profil) – 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 (.profil) 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 (optional)
    Project-level configuration for outlets and other overrides (for example to route generated Java sources into specific modules).

Profiles (.profil) and shared CMN models for base types or method types live in facilities and are only referenced via imports:

cmn
package com.example.app

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

platform Base

You normally do not edit the profile files from facilities; instead you select a platform in your CMN header and, optionally, override some properties (e.g. 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:

  • Learn the modeling concepts
    → Modeling overview

  • Look up CMN syntax details
    → CMN reference

  • Look up profile/platform syntax
    → Profile reference

  • Understand how model files are structured
    → Model file structure

  • See a complete working example project
    → JoinedWorkz quickstart repository (linked from the Examples section of this documentation).