JoinedWorkz
Docs1.3.81

Appearance

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

This quickstart requires Java 21 and Maven 3.9+.

The complete source project is maintained in the joinedworkz-quickstart repository on release/1.3.81. The release branch, POM and model shown below are kept synchronized.

Want a runnable application instead?

This Base-only Quickstart deliberately builds the POM and CMN model by hand so you can see the complete generation contract. To start a runnable JoinedWorkz Spring Boot application, optionally with an experimental Quasar frontend, use the Maven Archetypes.

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:

bash
mkdir joinedworkz-quickstart
cd joinedworkz-quickstart

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

xml
<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.81</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:

bash
mkdir model

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

cmn
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:

bash
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 these user-facing outputs:

text
src/generated/resources/openapi/com.example.joinedworkz.quickstart.yaml
diagram/api/com.example.joinedworkz.quickstart.html
diagram/types/com.example.joinedworkz.quickstart_cmn.html
diagram/types/org.joinedworkz.facilities.common.base.api_cmn.html

Open the YAML file in your editor: it contains the OpenAPI 3 specification for your simple Greeting API. The HTML files provide the matching OpenAPI viewer and datatype diagrams.

The CMN model and POM are authoritative inputs. OpenAPI and diagram output is replaceable; do not edit it directly. The ownership and regeneration reference explains cleanup and version-control alternatives.

The Base cartridges also generate HTML viewers and diagrams for this model. They do not generate Java sources or a runnable server application. Those are outside the scope of this Base-only first project.

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:

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