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 (.profile) 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 (.profile), 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 plus user-facing OpenAPI and 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 can be interpreted by a facility, for example for API/domain mapping. In release 1.3.80, tag-aware Java class generators also use the layer to select a source-tag-specific directory within their outlet. This routing behaviour is not generic to all generators.

Simple type
A scalar type. It can be annotated with a stereotype, specialise another simple type, and declare 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 { /* resource methods */ }

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:

resource /customers as Customer[] by id {
    readEntity()
    createEntity()
    queryEntities()
}

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, query, list)
• SpringBoot-specific entity CRUD helpers (createEntity, readEntity, updateEntity, queryEntities, deleteEntity)

Release 1.3.80 declares the Base name delete twice with different defaults. Base-only models should use a uniquely named project method type for deletion instead of relying on those ambiguous defaults. SpringBoot's deleteEntity does not have this ambiguity.

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

component CustomerBackend {
    provide /customers { /* implementation flow */ }
}

Components are used for backend structure, diagrams and implementation artefacts. In Base 1.3.80, a component also produces an additional OpenAPI document that aggregates all endpoints in its provide declarations, including provided resources imported from different CMN models.

Application
Assembles components into a larger system:

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

Applications can be used to generate application and component diagrams. They do not produce another application-wide OpenAPI aggregate in Base 1.3.80; OpenAPI aggregation happens per component.

---

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 { /* entity fields */ }

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='org.joinedworkz.common.java.Strategy'

Used in a contribution:

platform ExampleJava {
    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'

Verified outlet directories can be overridden for a project in joinedworkz.properties. Tagged routing depends on the selected facility and must be checked for the specific outlet and generator.

Cartridge
Bundles generators and connects them to outlets:

cartridge OpenApiCartridge
    implementation='org.joinedworkz.common.OpenApiCartridge'
    outlets=generatedOpenApi, generatedOpenApiHtml

Platforms decide which cartridges are applied.

joinedworkz.properties
A project-level configuration file in the project root. Among other facility-specific settings, it can override verified outlet directories.

outlet.generatedJavaSource.directory=src/generated/java

Only documented keys for the active JoinedWorkz release should be used; key patterns are not automatically available for every outlet.

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)
• user-facing OpenAPI and diagram cartridges

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.