Glossary

This glossary explains key terms used in the JoinedWorkz documentation. It is intentionally compact and will be extended over time.

---

Core concepts

JoinedWorkz
A model-driven generation platform. You describe your system in a canonical model, JoinedWorkz transforms it and runs generators (cartridges) to produce artefacts such as OpenAPI specs, Java classes, diagrams, etc.

Canonical Model Notation (CMN)
The primary DSL for modelling domain types, APIs, components and applications. CMN files use the extension .cmn.

Profile DSL (.profil)
The DSL for defining platforms, stereotypes, strategies, outlets and cartridges. Profiles describe how a canonical model should be interpreted and what generators should run.

Facility
A Maven module that bundles everything needed for one or more platforms: profiles (.profil), CMN models (e.g. base types, method types), cartridges, generators, strategies, etc.
Examples:

• common-base – Base platform
• common-java – Java platform
• spring-boot – SpringBoot platform

Platform
A named configuration that defines how a CMN model is interpreted for a specific technology stack.
Examples:

• Base – core types + OpenAPI/schema/diagram cartridges
• Java – extends Base with Java-specific mappings
• SpringBoot – extends Java with Spring MVC / REST mappings

Models select a platform in the header:

platform SpringBoot

---

Modelling elements (CMN)

Package
The namespace of a model file, defined in the header:

package com.example.customer

Optionally prefixed by a layer (see below).

Layer
An optional qualifier before package used to group packages by role, for example:

• core – internal domain model
• api – external API surface (DTOs, resources)
• backend – technical composition, components, applications

Layer names are used by platforms (e.g. SpringBoot) for outlet routing and for special behaviour such as API ↔ domain mapping.

Simple type
A scalar type based on a stereotype and optional parameters:

type<string> String(maxLength) maxLength=undefined

Simple types often carry validation or format properties (e.g. maxLength, pattern, format).

Complex type
A structured type with fields:

type<entity> Customer {
    id**:       Id
    firstName*: Name
    lastName*:  Name
    email:      String(255)
}

Complex types can:

• extend other complex types (extends)
• include fields from other types or field sets
• define operations

Enum
A type with a closed list of values, each optional with properties:

enum SetupType {
    NONE value="none"
    NP   value="NP"
    JP   value="JP"
}

Entity
A complex type with the stereotype entity. Entities usually have an identity (key field) and may map to persisted objects (e.g. JPA entities) depending on the platform.

DTO (Data Transfer Object)
A type used to transport data across boundaries (e.g. in APIs). DTOs are usually complex types in the api layer that:

• include fields from domain entities, and
• optionally hide internal fields.

Resource
Represents an externally visible endpoint (typically HTTP/REST).

resource /customers as Customer[] by id { ... }

Key parts:

• path (/customers)
• representation type (Customer or Customer[])
• identifier (by id)

Resource method
A method inside a resource that refers to a method type and optionally adds parameters and overrides:

readEntity()
createEntity()
queryEntities(^page: Integer, pageSize: Integer)

Method type (methodtype)
A reusable definition of HTTP semantics that resource methods refer to. There are:

• raw method types (pure HTTP verbs: get, post, put, …)
• opinionated method types with defaults (e.g. create, read, update, delete, query, list)
• SpringBoot-specific entity CRUD helpers (createEntity, readEntity, updateEntity, queryEntities, deleteEntity)

Component
Groups APIs into a deployable building block and defines which resources it provides:

component CustomerBackend {
    provide /customers { ... }
}

Components are used for backend structure and for generating diagrams and implementation artefacts.

Application
Assembles components into a larger system:

application CustomerApp {
    consists of {
        CustomerBackend
    }
    use {
        // external components
    }
}

Applications can be used to generate component diagrams and aggregated OpenAPI documents.

---

Profiles, stereotypes and properties

Stereotype
A reusable semantic tag that can be applied to model elements. Defined in profiles:

stereotype entity applicable for complextype

Usage in CMN:

type<entity> Customer { ... }

Stereotypes can:

• restrict where they apply (applicable for)
• inherit (specialization of)
• define propagation behaviour (e.g. along specialisation or references)

Property
Named, typed attributes that can be attached to model elements (via profiles) and given values in CMN models.
Examples: minLength, max, javaType, tableName.

Strategy
A strategy implementation used to compute derived property values. In a profile:

strategy JavaNamingStrategy implementation="..."

Used in a contribution:

contribute to field {
    property javaName: STRING strategy=JavaNamingStrategy
}

---

Generation concepts

Outlet
Describes where generated artefacts are written and with which behaviour (delete on clean, mark as derived, etc.). Example:

outlet generatedOpenApi
    directory = "./src/generated/resources/openapi"

Outlets can be overridden per project and per layer in joinedworkz.properties.

Cartridge
Bundles generators and connects them to outlets:

cartridge OpenApiCartridge
    implementation="..."
    outlets=generatedOpenApi, generatedOpenApiHtml

Platforms decide which cartridges are applied.

joinedworkz.properties
A project-level configuration file (in the project root) used to override:

• outlet directories (globally and per layer)
• package names (e.g. for cloned helper libraries)

Examples:

outlet.generatedJavaSource.directory=src/generated/java
outlet.generatedJavaSource.api.directory=../webapp/src/generated/java

override-package.org.iworkz.core=com.example.core

Handler
In the SpringBoot facility: a class/method that implements business logic for resource methods. The handler is referenced via a handler property in method types or resource methods and is wired into generated controllers and interfaces.

DataAccessService
A generated service class (SpringBoot + persistence facilities) that encapsulates CRUD operations for an entity. The SpringBoot CRUD method types (createEntity, readEntity, updateEntity, queryEntities, deleteEntity) use ${entity}DataAccessService as their handler target.

---

Facilities and platforms (summary)

Base facility / Base platform
Provides:

• core simple types (e.g. String, Integer, Decimal, Date, …)
• method types for REST APIs (raw + opinionated)
• generic cartridges (OpenAPI, schema, diagrams)

Java facility / Java platform
Extends Base with:

• Java-specific type mappings (javaType)
• naming strategies (javaName)
• Java-generation cartridges

Spring Boot facility / SpringBoot platform
Extends Java with:

• Spring MVC / REST mappings
• controller and handler generation
• special handling of the api layer for DTO ↔ domain mapping
• entity CRUD helpers in SpringBootApi.cmn

---

This glossary is not complete, but it should give you a solid starting point for the most frequently used JoinedWorkz concepts.