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

Prerequisites

Before you start, make sure you have:

• Java 17 or newer
  JoinedWorkz 1.3.74 is tested with Java 17 and Java 21.
• Maven 3.8+ 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-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <joinedworkz.version>1.3.74</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.joindeworkz.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. Package
   package com.example.joindeworkz.quickstart declares the namespace of your model. It is also used in the name of generated artifacts.

2. Import
   import org.joinedworkz.facilities.common.base.api pulls in a base model that defines common REST method types (such as create and read) and basic types (such as String).

3. Platform
   platform Base selects the platform definition to use. The Base platform is provided by the JoinedWorkz libraries and includes cartridges for OpenAPI generation, diagram generation and a debug cartridge.

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

5. Methods
   create() 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
   • 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 base type defined in the imported base model.

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.joindeworkz.quickstart.yaml

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

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 existing joinedworkz-quickstart Maven project.
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.