Glossary

This glossary explains key terms used in the JoinedWorkz documentation.

---

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 artifacts such as OpenAPI specs, Java classes, diagrams, etc.

Canonical Model Notation (CMN)
The primary DSL for modeling 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

---

Modeling 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, case-sensitive identifier immediately before package, for example api package com.example.customer. It can group packages by role:

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

The declared CMN layer normally becomes the effective layer for outlet routing. A generator can assign a different effective layer to a particular output, for example api for SpringBoot controller and API-interface files. An exact layer-specific outlet mapping wins; otherwise the global outlet directory applies. Facilities can additionally give selected layer names their own semantics, for example for API/domain mapping. Other layer names remain valid and need not have meaning beyond project structure and routing.

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 named values. A selected profile can supply stereotypes and properties that refine their meaning:

enum<integer> SetupType {
    NONE: 10
    NP:   20
    JP:   30
}

The integer stereotype gives each public enum name an explicit mapped code; see Enumerations.

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 generated transport-oriented representation of a complex CMN type. A CMN type need not be declared in the api layer for SpringBoot to generate its DTO. An optional api-layer view can specialise the external representation, for example by including selected source fields and hiding 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, deleteInstance, query, list)
• SpringBoot-specific entity CRUD helpers (createEntity, readEntity, updateEntity, queryEntities, deleteEntity)

Base uses delete for the raw HTTP method type and deleteInstance for the opinionated instance method. When migrating an older model, select the intended semantics explicitly; see the upgrade guide.

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 artifacts. 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; 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 behavior (e.g. along specialization 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 DI-managed implementation that computes a calculated Core Model property during CMN transformation. A Profile declares the implementation:

strategy TextReportLabelStrategy
    implementation="com.example.textreport.TextReportLabelStrategy"

It then associates the Strategy with an applicable property:

platform TextReport specialization of Base {
    contribute to complextype {
        property reportLabel: STRING strategy=TextReportLabelStrategy
    }
}

Generators read the calculated property from the transformed Core Model; they do not invoke the Strategy again. See Profile Strategies and calculated properties.

---

Generation concepts

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

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

Declared outlet directories can be overridden for a project in joinedworkz.properties. Layer-specific routing matches the effective layer of an output file; facilities and generators can give selected layer names additional semantics.

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 Maven module root or JoinedWorkz Studio project root. Among other facility-specific settings, it can override declared outlet directories.

outlet.generatedJavaSource.directory=src/generated/java

Only documented keys for the active JoinedWorkz release should be used. The central configuration reference is not a closed JoinedWorkz-wide registry: other facilities can define additional keys and outlets and must document their contracts.

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

Quasar facility / Quasar platform Experimental facility that extends Base and generates replaceable Vue/Quasar frontend fragments for modeled component<ux> elements. A runnable application requires a manually maintained application shell.

---

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