JoinedWorkz
Docs1.3.81

Appearance

CMN — For AI Tools ​

This page provides a compact, AI-optimized overview of the CMN modeling language used in JoinedWorkz.

Use this as a guide when analyzing or modifying CMN models.

Resolve the documentation version first

Before applying this syntax or semantics to a project, read its exact Maven plugin version and the versions of all JoinedWorkz facility dependencies. The plugin and every facility must use the same exact JoinedWorkz release. If they differ, report the unsupported version mixture and do not select one release's documentation. Resolve the matching documentation mount through the public machine-readable catalogue at https://www.joinedworkz.org/docs/versions.json. Do not combine this language contract with a different JoinedWorkz release.

What CMN is ​

CMN (Canonical Model Notation) is the modeling language of JoinedWorkz.

It describes:

  • domain types
  • APIs
  • resources
  • application structure

CMN defines system intent, not implementation details.

Key principle ​

CMN is model-driven, not code-driven.

Do not think in Java classes or database tables.

Think in:

  • domain concepts
  • APIs
  • structure
  • behavior

Basic structure of a model ​

A typical .cmn file contains:

cmn
package com.example.project

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

platform SpringBoot

type Example {
    field: String
}

resource /example as Example {
    create()
    read()
}

Core elements ​

Package ​

Defines the namespace:

cmn
package com.example.project

Import ​

Imports reusable definitions from facilities:

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

Platform ​

Defines the target environment:

cmn
platform SpringBoot

Type ​

Defines a domain structure:

cmn
type Request {
    id: Long
    description: String
}

Resource ​

Defines an API endpoint:

cmn
resource /requests as Request {
    create()
    read()
    update()
}

Modeling rules ​

1. Model intent, not implementation ​

Good:

  • domain structure
  • API shape

Bad:

  • database details
  • framework-specific annotations

2. Keep models simple ​

  • prefer clear, flat structures
  • avoid unnecessary complexity

3. Separate concerns ​

Use different files for:

  • domain
  • API
  • application
  • configuration

Give every root package and subpackage a unique fully qualified name. Never split one package across multiple .cmn files; connect distinct packages with imports instead.

4. Use platform abstraction ​

  • avoid hardcoding technology details
  • use platform and facilities instead

Common patterns ​

CRUD resource ​

cmn
resource /requests as Request {
    create()
    read()
    update()
}

Domain type ​

cmn
type User {
    id: Long
    name: String
}

Common mistakes ​

Thinking in Java ​

Wrong:

  • adding implementation details
  • designing classes instead of models

Editing generated code instead of model ​

Fix:

  • update CMN model
  • regenerate

This includes generated OpenAPI. Descriptions, summaries and request/response examples are authoritative CMN metadata; do not patch them into replaceable YAML or generated Java annotations. Preserve existing documentation blocks when changing a declaration. New metadata uses @description, @summary, @title, @request, @response and example: exactly as defined in Common CMN syntax. Preserve an existing value: when it separates an example description from its value, but do not add that optional boundary mechanically to ordinary multiline values.

Before cleanup or manual changes, classify the artifact with the generated-output ownership matrix. First-cut files and versioned migration history are not ordinary replaceable output.

Mixing concerns ​

Wrong:

  • domain + API + runtime logic in one place

Over-specifying ​

Wrong:

  • too many fields
  • too much structure too early

AI usage guidance ​

When modifying CMN:

  1. Identify the correct element:

    • type
    • resource
    • platform

  2. Keep changes minimal and consistent.

  3. Do not introduce implementation details.

  4. Prefer extending existing models over duplicating them.

  5. Treat documentation and examples as part of the model contract. Update them together with the affected type, field, operation or response and verify the generated target artifact.

Relationship to generation ​

CMN does not define code directly.

It defines:

  • structure
  • intent

Generation produces:

  • Java code
  • APIs
  • database migrations
  • other artifacts

Summary ​

CMN is:

  • declarative
  • model-driven
  • platform-independent as far as possible

Use it to define what the system is, not how it is implemented.