Quickstart: Your first JoinedWorkz project

This quickstart walks you through creating and building a minimal JoinedWorkz project using Maven. You will:

• create a new Java/Maven project
• add a small JoinedWorkz model (only an API)
• run the JoinedWorkz generator from Maven
• inspect the generated OpenAPI document
• optionally open the project in JoinedWorkz Studio

Estimated time: 10–15 minutes

Release baseline and verification

This page targets JoinedWorkz 1.3.80, Java 21 and Maven 3.9+. The exact POM and CMN model shown below were built from a clean directory with the published 1.3.80 artifacts on 2026-07-26. This page is the canonical source for the first quickstart until the public joinedworkz-quickstart repository has been aligned with this baseline.

Prerequisites

Before you start, make sure you have:

• Java 21
• Maven 3.9 or newer installed and on your PATH: mvn -v
• A code editor or IDE of your choice (IntelliJ IDEA, VS Code, Eclipse, …)

JoinedWorkz Studio is not required for this quickstart. You can complete everything using your normal editor and Maven. If you want a graphical modeling editor, see the dedicated Install JoinedWorkz Studio guide.

1. Create the project

Create a directory and an empty Maven project:

mkdir joinedworkz-quickstart
cd joinedworkz-quickstart

Create a file pom.xml in this directory with the following content:

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>joinedworkz-quickstart</artifactId>
    <version>1.0.0</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <joinedworkz.version>1.3.80</joinedworkz.version>
    </properties>

    <build>
        <resources>
            <!-- model files are treated as resources so they are available on the classpath -->
            <resource>
                <directory>model</directory>
            </resource>
            <!-- generated artifacts (e.g. OpenAPI) are also added as resources -->
            <resource>
                <directory>src/generated/resources</directory>
            </resource>
        </resources>

        <plugins>
            <!-- JoinedWorkz generator plugin:
                 parses the model, transforms it and runs the configured generators -->
            <plugin>
                <groupId>org.joinedworkz.cmn</groupId>
                <artifactId>cmn-maven-plugin</artifactId>
                <version>${joinedworkz.version}</version>
                <executions>
                    <execution>
                        <?m2e ignore?>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>

    </build>

    <dependencies>
        <!-- modeling and generation tools (provided) -->
        <dependency>
            <groupId>org.joinedworkz.facilities</groupId>
            <artifactId>common-base</artifactId>
            <version>${joinedworkz.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

</project>

A few important points:

• The JoinedWorkz generator plugin (cmn-maven-plugin) contains the parser, model transformation and orchestration of generators.
• The common-base dependency provides shared model fragments, such as the base API model and common types used by your own models.
• Additional platforms and generators are added as normal dependencies and will be picked up by the plugin at runtime.

2. Add a minimal model

Create a directory model in the project root:

mkdir model

Inside it, create a file quickstart-model.cmn with the following content:

package com.example.joinedworkz.quickstart

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

platform Base

resource /hello as Greeting {

    create()
    read()

}

type Greeting {
    message: String
}

What this model does:

1. Packagepackage com.example.joinedworkz.quickstart declares the namespace of your model. It is also used in the name of generated artifacts.

2. Importimport org.joinedworkz.facilities.common.base.api pulls in a base model that defines common REST method types such as create and read. Base types such as String come from the Base facility's org.joinedworkz.facilities.common.base model and are available through CMN's global default imports.

3. Platformplatform Base selects the platform definition to use. The Base platform is provided by the JoinedWorkz libraries. Its user-facing outputs in this quickstart are produced by the OpenApiCartridge and DiagramCartridge.

4. Resourceresource /hello as Greeting { ... } defines a REST-like resource with the path /hello, represented by the Greeting type.

5. Methodscreate() and read() reference method types from the imported base model. In the default base model, they map to:

   • create → POST /hello with a body containing a Greeting and a 201 Created response containing the generated Id (UUID)
   • read → GET /hello with a 200 OK response returning a Greeting

6. Types The complex type Greeting has a single property message of type String. String is a type supplied by the Base facility.

The file extension .cmn stands for Canonical Model Notation, the textual DSL used by JoinedWorkz.

3. Run the Maven build and generate the API

From the project root, run:

mvn clean package

During the build, the JoinedWorkz Maven plugin will:

1. load all models from the model directory
2. parse and transform them into the internal canonical model
3. determine the platform(s) referenced by your model
4. load the corresponding cartridges and generators from the classpath
5. execute the generators

For the Base platform in this quickstart, one of the cartridges generates an OpenAPI document for the /hello resource.

After the build finishes, you should find:

src/generated/resources/openapi/com.example.joinedworkz.quickstart.yaml

Open this file in your editor: it contains the OpenAPI 3 specification for your simple Greeting API.

The verification build also produced the Base HTML viewers and diagrams. It did not generate Java sources or a runnable server application. Those are outside the scope of this Base-only first success.

4. (Optional) Use the generated OpenAPI

The generated OpenAPI YAML can be used to:

• generate client SDKs or server stubs with standard OpenAPI tools
• import the API into API gateways or management platforms
• serve as documentation for other teams

Because the file is located under src/generated/resources and that directory is configured as a Maven resource, it can be packaged with your application or published as a separate artifact.

5. (Optional) Open the project in JoinedWorkz Studio

If you prefer a graphical modeling experience:

1. Install JoinedWorkz Studio and configure your trial license key (see the dedicated Install JoinedWorkz Studio guide).
2. Start Studio and open the joinedworkz-quickstart Maven project created in this guide.
3. Navigate to model/quickstart-model.cmn and edit the model.
4. Re-run mvn clean package to regenerate the OpenAPI file with your changes.

Note: JoinedWorkz Studio is the only component that requires a license key. The model transformation engine, generators and the Maven plugin are freely available and can be used without Studio.

Next steps

From here you can:

• learn more about the core concepts
• explore the DSL in more detail in the Modeling section
• follow the first How-to guide: Create a model and apply an existing generator.

Need help?

If you get stuck or have questions, you can ask the JoinedWorkz Assistant:

👉 https://chatgpt.com/g/g-69d7ffb919808191b9ea54e6010e67f1-joinedworkz-assistant

• ask questions about modeling and concepts
• get help with errors or setup
• submit feedback directly to the maintainers

Using AI

For AI-assisted development, see:

👉 AI Context