JoinedWorkz
Docs1.3.81

Appearance

Base facility ​

Support status

Stable

The Base facility provides the platform-independent modeling foundation used by all other publicly documented JoinedWorkz facilities. It generates API specifications and diagrams, but no programming-language implementation or runnable server.

1. Maven artifact and platform ​

Add the facility to the model module:

xml
<dependency>
    <groupId>org.joinedworkz.facilities</groupId>
    <artifactId>common-base</artifactId>
    <version>${joinedworkz.version}</version>
    <scope>provided</scope>
</dependency>

The artifact contributes:

  • profile package org.joinedworkz.facilities.common.profiles.base;
  • platform Base;
  • CMN package org.joinedworkz.facilities.common.base with common types; and
  • CMN package org.joinedworkz.facilities.common.base.api with resource method types.

2. Supported modeling and generation ​

Base provides:

  • simple types such as String, Integer, Long, Decimal, Date, Time, Timestamp, Boolean, Binary and Id;
  • constraints and common stereotypes for types, fields, services, components and associations;
  • raw HTTP method types get, post, put, patch and delete;
  • opinionated method types create, start, execute, read, downloadText, update, deleteInstance, query and list;
  • model-scoped OpenAPI documents for non-abstract resources;
  • additional component-scoped OpenAPI documents that aggregate all endpoints provided by a component; and
  • HTML diagrams for types, components, APIs, applications, landscapes and modeled processes where the relevant CMN content exists.

The active cartridges are OpenApiCartridge and DiagramCartridge.

New models use the canonical Base property names min, max, maxDigits, decimals, pagination, and sort. See the property migration guide for deprecated compatibility names and the distinct paging behavior.

3. Public and advanced configuration ​

  • rest.useVendorSpecificMimeType — public; defaults to false. Enables vendor-specific REST media types unless the model overrides the behavior.
  • openapi.qualifiedSchemaName — advanced; defaults to false. Uses qualified OpenAPI schema names.

Generic cartridge.<name>.enabled configuration can disable an active cartridge. Outlet directories can be changed with outlet.<outlet>.directory. See the joinedworkz.properties reference for parsing and precedence.

4. Outputs and ownership ​

All regular Base outputs are replaceable:

  • generatedOpenApi defaults to src/generated/resources/openapi;
  • generatedOpenApiHtml defaults to diagram/api; and
  • generatedDiagram defaults to diagram.

Change the CMN model or configuration and regenerate these files; do not edit them manually.

5. Minimal model ​

cmn
package com.example.greeting

import org.joinedworkz.facilities.common.base
import org.joinedworkz.facilities.common.base.api

platform Base

resource /hello as Greeting {
    read()
}

type Greeting {
    message: String
}

6. Build and expected result ​

With the JoinedWorkz Maven plugin configured, run:

bash
mvn clean package

The default OpenAPI output for this model is:

text
src/generated/resources/openapi/com.example.greeting.yaml

Base also writes the corresponding OpenAPI viewer and applicable diagram pages. It does not generate Java sources, application bootstrap code or a deployable service. Continue with Java or SpringBoot when implementation code is required.

7. Boundaries ​

  • Base is technology-independent; it does not select a runtime framework.
  • A component can aggregate endpoints from several provided resource models. Applications do not produce another application-wide OpenAPI aggregate.
  • Base assigns no special meaning to individual layer names. The generic generator runtime nevertheless uses the model layer as the default effective layer for OpenAPI and diagram output.
  • Every CMN package must have a unique technical namespace.

8. Related pages ​