Releases, compatibility and support
JoinedWorkz releases coordinate the model language, Maven plugin, facilities and, when used, JoinedWorkz Studio. This page defines the public documentation baseline, explains facility lifecycle labels and routes support requests to the appropriate public channel.
1. Compatibility matrix
| Area | Baseline |
|---|---|
| JoinedWorkz model/build stack | 1.3.81 |
| JoinedWorkz Studio | 1.3.81 |
| Java | 21 |
| Maven | 3.9 or newer |
| Maven Archetypes | 1.0.0 targets JoinedWorkz 1.3.81 |
Use the exact same JoinedWorkz version for cmn-maven-plugin and every facility in one build. Use the Studio distribution from the same coordinated release when working in Studio; Maven generation does not require Studio or a Studio license.
Archetype versions are released independently from the JoinedWorkz model/build stack. Use Archetype 1.0.0 with JoinedWorkz 1.3.81; do not infer compatibility from matching version numbers.
The stable facilities are Base, Java and SpringBoot. Quasar is experimental; its generated output and manual application shell have no stable compatibility guarantee.
This is a documentation and component-alignment matrix. It does not announce a long-term-support period or promise maintenance for a fixed number of older releases. Use the release baseline on the relevant documentation page and include that exact release when requesting help.
Spring Boot, database, Node.js and frontend-library versions can also be constrained by a concrete application or example. They are not inferred from the JoinedWorkz version alone. A custom facility must publish its own runtime and compatibility contract.
2. Version-alignment rules
Keep one JoinedWorkz version across:
org.joinedworkz.cmn:cmn-maven-plugin;- all
org.joinedworkz.facilitiesdependencies used by the model module; and - project-owned facilities compiled against that JoinedWorkz release.
Do not combine a plugin from one release with profiles or cartridge implementations from another. Maven can resolve that mixture without proving that its profile model, Java APIs and generated output are compatible.
Versions ending in -SNAPSHOT are development builds. They are not a public documentation, example or support baseline. Use exact released versions in project POMs and in reproducible support cases.
3. Lifecycle labels
Stable
A stable public facility or configuration contract is intended for regular application development. Incompatible changes require an explicit migration path and deprecation policy. Stable does not mean that generated files remain byte-identical after an upgrade: generator changes can require clean regeneration and review.
Experimental
An experimental facility is available for evaluation. Its model contract, configuration, generated structure and application-shell requirements can change between releases without the stable compatibility guarantee. Quasar is the experimental facility documented on this site.
Deprecated
A deprecated public contract remains available only to support migration. Its documentation names the replacement, compatibility behavior and removal status. Do not introduce deprecated configuration into a new project.
Internal
Internal profiles, facilities, keys and implementation classes are not public API and have no compatibility guarantee. Their presence in source code or a published Maven artifact does not make them a supported alternative.
The facility matrix lists the built-in facilities covered by this public documentation. It is not a closed registry: independently developed facilities can define additional status and compatibility policies.
4. Deprecations
Base profile properties
The following Base property names are deprecated:
minValue→min;maxValue→max;precision→maxDigits;scale→decimals;sorting→sort; andpaging→ migrate deliberately topagination.
The first five names remain compatibility aliases. Their use reports JW_DEPRECATED_PROPERTY; conflicting simultaneous old and new values report JW_PROPERTY_ALIAS_CONFLICT. paging is deprecated but remains a separate behavior, not an alias. For a response without responseContext, moving to pagination changes the generated frontend collection path from response.data.data to response.data.content. An explicit responseContext instead keeps the data collection member and adds a context member, independently of that migration.
No removal release has been announced. New models use only the canonical names. The upgrade guide describes safe handling of simultaneous declarations and the paging migration boundary.
Public SpringBoot API outlet override
outlet.generatedApiSource.directory is deprecated for SpringBoot API output.
- Use instead:
outlet.generatedJavaSource.api.directory - Compatibility: the legacy property remains accepted. If both properties are present, the new property wins.
- Removal status: no removal release has been announced. Migrate now and do not use the legacy property in new configuration.
The replacement routes API DTOs, controller classes and API interfaces through the api layer of the normal generatedJavaSource outlet. See the upgrade guide for the change procedure.
Advanced Base developer diagnostic
For facility and cartridge authors, SchemaCartridge and its generatedSchema outlet are replaced by CoreModelDiagnosticCartridge and generatedCoreModelDiagnostics.
- Compatibility: the old Java cartridge class remains as a deprecated wrapper for custom legacy profiles. Standard profiles no longer register the old cartridge or outlet.
- Removal status: the wrapper is retained for the transition. Custom profiles should migrate before moving to a later JoinedWorkz release.
This diagnostic is disabled by default and is not an application-facing schema generator. The facility-author migration describes the exact replacement.
Experimental Quasar widget contract
An application-provided widget processed by the experimental Quasar facility uses a valid componentRef. The Quasar Cartridge rejects the custom stereotype on widgets, including a widget that also declares componentRef.
This is an experimental-facility contract change, not a global removal of the Base custom stereotype. Services and other facilities retain their existing contracts. See the Quasar facility and the upgrade guide.
Experimental Quasar action-alias contract
A page action processed by the experimental Quasar facility must have a valid, non-reserved JavaScript binding identifier. The Cartridge reports quasar.invalidActionAlias before output for aliases that would produce invalid JavaScript or duplicate another Action alias on the same page. It reports quasar.conflictingActionAlias when an otherwise valid alias would reuse another binding actually generated for that Page, such as a Page field, data or Condition binding, event handler or generated helper. Valid, non-conflicting aliases are emitted unchanged. This contract is independent of Resource operationName.
Every generated Action function returns a Promise. Supported assignments, consumed Resource operations and alternatives run in model order; asynchronous operations are awaited sequentially and the Promise retains the last asynchronous result. Unsupported commands report quasar.unsupportedActionCommand before output. A stereotyped Action keeps its Promise result and rejection semantics while delegating lifecycle handling to the manual application's CommandHelper.
See the Quasar facility and the upgrade guide.
5. Support channels
Technical bugs and enhancements
Use the public JoinedWorkz work-item tracker for reproducible technical defects and enhancement proposals that can be discussed publicly.
Before opening an item, check the Troubleshooting reference. Include the smallest reproducible case and the diagnostic information listed in its “Information to collect” section.
Commercial, licensing and project support
For commercial support, licensing questions, confidential project context or custom-generator work, use the JoinedWorkz contact page or email info@joinedsystems.eu.
Available scope and response arrangements are agreed through that contact channel. This documentation does not promise a particular response time or support period.
Do not post credentials, repository tokens, license files or unrelated proprietary model content in a public work item. Sanitize configuration and prefer a minimal reproducer. Contact JoinedSystems before sharing material that cannot be public.
6. Information to include
A useful technical request normally contains:
- the exact plugin and facility versions;
- Java and Maven versions, plus Node.js and npm for a frontend failure;
- the model module and exact command that failed;
- the first actionable diagnostic and complete nested cause;
- stable codes such as
JW_CONFIG_*orCMN_DUPLICATE_PACKAGE; - the smallest relevant CMN or profile fragment;
- sanitized
joinedworkz.propertiesentries; - relevant JoinedWorkz lines from
mvn dependency:tree; - effective outlet routes and ownership classification; and
- whether the problem occurs in Maven, Studio or both.
The complete checklist and symptom-first recovery paths are maintained in Troubleshooting.