Profile reference

This page is a compact syntax reference for the JoinedWorkz profile DSL (.profile) as available in release 1.3.80. Profiles describe platforms and how generators interpret canonical models.

Application developers normally consume profiles supplied by facilities. The sections about defining stereotypes, strategies, outlets, cartridges, settings, and platforms are advanced, version-bound information for facility and cartridge authors; they are not yet a complete extension-author contract.

1. File structure

A profile can declare a package, imports, and profile model elements:

package com.example.profile

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

strategy ExampleStrategy implementation='com.example.ExampleStrategy'
outlet generatedExample directory='./target/generated-example'
cartridge ExampleCartridge
    implementation='com.example.ExampleCartridge'
    outlets=generatedExample

The registered file extension is .profile.

2. Stereotypes

Stereotypes are reusable annotations that can be attached to selected model element types:

package com.example.profile

stereotype entity
    applicable for complextype
    not propagated by specialization

stereotype key
    applicable for field
    propagated by specialization, including

stereotype number applicable for simpletype
stereotype integer
    applicable for simpletype
    specialization of number

• applicable for declares the allowed model element selections.
• specialization of derives one stereotype from another.
• propagated by and not propagated by control inheritance along the listed propagation paths.

The stereotype is used in CMN in front of the element it annotates. A key field is commonly written with the ** shorthand:

type<entity> Customer {
    id**: Id
}

3. Strategies and property contributions

A strategy provides the implementation for a calculated profile property:

package com.example.profile

strategy JavaNamingStrategy
    implementation='org.joinedworkz.common.java.Strategy'

strategy JavaTypeStrategy
    implementation='org.joinedworkz.common.java.JavaTypeStrategy'

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

    contribute to type {
        property javaType: STRING strategy=JavaTypeStrategy
    }
}

contribute to can occur in a platform { ... } body and, for stereotype-specific contributions, in a stereotype body. A contribution can select a model element type, a stereotype, or a nested element selection.

4. Outlets

Outlets define where generated artifacts are written and how JoinedWorkz treats the target directory:

package com.example.profile

abstract outlet StandardOutput
    createNotExistingDirectory=true
    overwriteExistingFiles=true
    markAsDerived=true
    deleteFilesOnCleanBuild=true
    cleanWholdDirectoryOnCleanBuild=false
    keepLocalHistory=true

outlet generatedOpenApi specialization of StandardOutput
    directory='./src/generated/resources/openapi'

outlet generatedOpenApiHtml specialization of StandardOutput
    directory='./diagram/api'

cleanWholdDirectoryOnCleanBuild is intentionally spelled Whold here. It is the exact property name published in release 1.3.80; changing it to Whole would create a different, ineffective property.

Outlet properties follow the declaration directly; outlets do not have a braced body. specialization of inherits properties from another outlet.

When a project contains joinedworkz.properties, it can override a verified outlet directory, for example:

outlet.generatedJavaSource.directory=../service/src/generated/java

In release 1.3.80, SpringBoot projects should keep this file present even when it is empty; missing and empty do not yet have the intended equivalent behaviour.

The set of supported outlets and any source-tag-specific routing are defined by the selected facility. Do not infer a property key solely from a generated directory name.

5. Cartridges (extension authors)

This section is for facility and cartridge developers. Cartridges connect generator implementations to one or more outlets:

package com.example.profile

outlet generatedDiagram directory='./diagram'
outlet generatedSchema directory='./target/joinedworkz/schema'
outlet generatedOpenApi directory='./src/generated/resources/openapi'
outlet generatedOpenApiHtml directory='./diagram/api'

cartridge DiagramCartridge
    implementation='org.joinedworkz.common.DiagramCartridge'
    outlets=generatedDiagram

cartridge SchemaCartridge
    implementation='org.joinedworkz.common.SchemaCartridge'
    outlets=generatedSchema

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

The SchemaCartridge shown in these extension-author examples is a diagnostic tool despite its name. It writes selected elements of the transformed CMN Core model to separate .json diagnostic files for facility/cartridge development and debugging. It does not generate SQL, a database schema or a normal application artifact. In release 1.3.80, some of these .json files use single-quoted names or values and are therefore not consistently valid JSON; they are not a stable machine-readable contract. Application-developer guides and examples therefore do not present generatedSchema as a product output or configuration target.

A platform decides which cartridges are applied. A CMN model can exclude a cartridge selected by its platform:

platform SpringBoot exclude DtoCartridge

6. Settings

A setting names the implementation used to wire a platform:

package com.example.profile

setting CommonSetting
    implementation='org.joinedworkz.common.CommonSetting'

Settings are relevant to facility maintainers. Application models normally only select the resulting platform.

7. Platforms (extension authors)

A platform applies cartridges and contributes properties to model elements. This self-contained example uses the same syntax and public names as the Base profile:

package com.example.profile

stereotype string applicable for simpletype
stereotype entity
    applicable for complextype
    not propagated by specialization

outlet generatedDiagram directory='./diagram'
outlet generatedSchema directory='./target/joinedworkz/schema'
outlet generatedOpenApi directory='./src/generated/resources/openapi'
outlet generatedOpenApiHtml directory='./diagram/api'

cartridge DiagramCartridge
    implementation='org.joinedworkz.common.DiagramCartridge'
    outlets=generatedDiagram
cartridge SchemaCartridge
    implementation='org.joinedworkz.common.SchemaCartridge'
    outlets=generatedSchema
cartridge OpenApiCartridge
    implementation='org.joinedworkz.common.OpenApiCartridge'
    outlets=generatedOpenApi, generatedOpenApiHtml

setting CommonSetting
    implementation='org.joinedworkz.common.CommonSetting'

platform Base setting=CommonSetting {
    apply cartridge DiagramCartridge
    apply cartridge SchemaCartridge
    apply cartridge OpenApiCartridge

    contribute to simpletype<string> {
        property minLength: INTEGER
        property maxLength: INTEGER
        property pattern: STRING
        property javaType: STRING
        property format: STRING
    }

    contribute to complextype<entity> {
        property tableName: STRING not propagated by specialization
    }

    contribute to complextype<entity>.field {
        property columnName: STRING
    }
}

7.1 Platform inheritance and overrides

A derived platform can apply more cartridges and override contributed properties:

package com.example.profile

stereotype decimal applicable for simpletype

outlet generatedJavaSource directory='./src/generated/java'
cartridge DtoCartridge
    implementation='org.joinedworkz.common.java.DtoCartridge'
    outlets=generatedJavaSource

platform Base {
    contribute to simpletype {
        property javaType: STRING
    }
}

platform Java specialization of Base {
    apply cartridge DtoCartridge

    contribute to simpletype<decimal> {
        override javaType value='java.math.BigDecimal'
    }
}

DtoCartridge is the Java-profile cartridge name in release 1.3.80.

8. Important profile keywords

• Structure: package, import, as
• Definitions: stereotype, strategy, outlet, cartridge, setting, constraint, platform
• Relationships: specialization of, applicable for, propagated by, not propagated by
• Platform body: add stereotype, apply cartridge, redirect ... to ..., contribute to, property, override

For application-facing CMN usage, continue with the CMN reference. Facility authors should treat this page as release-specific orientation until the extension-author guide is completed and validated against the published cartridge API.