Profile-controlled property propagation

JoinedWorkz lets Facility authors control whether scalar CMN properties are copied across selected model relationships. This is an advanced Profile DSL contract. Application developers normally consume the rules supplied by their selected Facility instead of defining them.

Start with the Profile author reference if you have not yet defined a Profile Contribution.

1. Which properties this contract controls

A Profile Contribution declares a property that can occur on selected CMN model elements:

platform Example specialization of Base {
    contribute to simpletype, field {
        property displayWidth: INTEGER propagated by type
    }
}

displayWidth is a CMN model property. Its value belongs to a model element and is available in the transformed Core Model. A Cartridge can read that value and give it a generated effect.

This is different from a key in joinedworkz.properties. Those keys configure a project build or a Cartridge and do not propagate between model elements. See the joinedworkz.properties reference for that separate contract.

Facilities can contribute additional model properties and implement their effects in their own Cartridges. Consequently, the names used on this page are examples, not a complete JoinedWorkz property registry.

2. Declaring the rule

The unrestricted form has no propagation clause: property displayWidth: INTEGER.

It preserves the established behavior: JoinedWorkz can copy the property along every supported relationship for which the property is applicable. If no applicable Profile definition can be found for a source property, JoinedWorkz likewise retains this unrestricted historical behavior. A propagation clause narrows only the property definition on which it is declared.

A positive rule permits only the named relationships: property displayWidth: INTEGER propagated by type, specialization.

A negative rule permits the supported relationships except those named: property internalHint: STRING not propagated by referencing, including.

The available keywords are specialization, referencing, including, type, stereotype and methodtype. A declaration uses either the positive or the negative form. An empty positive or negative list is not valid Profile syntax.

The rule attached to the property's source model element decides whether the value can cross a relationship. A differently configured property with the same name on the target does not replace that source-side decision. This is important when one Contribution makes a property available on both the source and target element kinds.

3. Supported propagation relationships

Each keyword identifies one concrete source-to-target relationship:

• specialization copies a property from a base simple type, complex type or enumeration to its specializing type.
• type copies a property from a field's declared type to that field.
• including copies a property from an explicitly included base field to the resulting field.
• stereotype copies a property supplied by the selected stereotype to a field, type or operation on which that stereotype is applied.
• methodtype copies a property from a resource method type to a resource method that uses it.
• referencing copies a property from a referenced field or widget to a page content element. This includes direct field and widget references and the field/widget sources of a widget-with-data content element.

The keywords describe property flow; they do not cause the corresponding CMN relationship to be created. For example, propagated by type has an effect only when a field actually declares the source type.

Property propagation and stereotype propagation are separate contracts. The stereotype keyword above controls properties supplied through an applied stereotype. It does not decide whether a stereotype itself is inherited, included or referenced. A propagated by ... clause on a stereotype declaration controls that separate stereotype behavior.

4. Local values have priority

A value written directly on the target model element wins over a propagated value. Propagation fills a value only when the target has not already supplied one.

For example, the Profile makes displayWidth available on simple types and fields and permits the type relationship:

platform Example specialization of Base {
    contribute to simpletype, field {
        property displayWidth: INTEGER propagated by type
    }
}

The type value reaches shortName, while the local field value overrides it for fullName:

package com.example.customer

type ShortText displayWidth=20

type Customer {
    shortName: ShortText
    fullName: ShortText displayWidth=40
}

The transformed fields therefore have displayWidth=20 and displayWidth=40, respectively. The generated effect still depends on a Cartridge that consumes displayWidth.

The same priority applies to specialization:

platform PropagationExample {
    contribute to simpletype {
        property wireFormat: STRING propagated by specialization
    }
}

package com.example.customer

type ExternalId wireFormat='uuid'
type CustomerId specialization of ExternalId
type LegacyCustomerId specialization of ExternalId wireFormat='decimal'

CustomerId receives uuid; LegacyCustomerId keeps its local decimal value.

5. Including a field

including applies to one explicitly included field:

platform PropagationExample {
    contribute to field {
        property exportName: STRING propagated by including
    }
}

package com.example.customer

type Text

fieldset CommonFields {
    externalId: Text exportName='customer_id'
}

type Customer {
    CommonFields.externalId
}

The included externalId field receives exportName='customer_id'. A property written after CommonFields.externalId would take priority.

An include and a reference are not interchangeable. An include creates a field from another field declaration and uses including. A page content element that points to an existing field or widget uses referencing.

Wildcard field expansion, such as CommonFields.*, is a separate structural feature. It is outside this scalar property-propagation contract. Do not use a property's including rule to predict or filter which fields a wildcard expands.

6. Referencing from page content

The following Profile rule lets a widget property reach a content element:

platform PropagationExample {
    contribute to _widget, _contentItem {
        property density: STRING propagated by referencing
    }
}

package com.example.customer

widget CustomerCard density='compact'

component CustomerUI {
    page Overview {
        content {
            CustomerCard
            CustomerCard density='comfortable'
        }
    }
}

The first content element receives compact; the second keeps its local comfortable value.

A content element can combine a widget with referenced data. Its priority is:

1. a value written locally on the content element;
2. a value propagated from the referenced field; and
3. a value propagated from the widget.

This ordering lets field-specific metadata refine a reusable widget while still allowing one content occurrence to override both sources. Nested content elements apply the same rule independently at each level.

7. Special property categories

The generic six-mode propagation step does not copy a calculated property. A calculated property is created by a Profile Strategy during transformation; its definition and lifecycle are documented in Profile Strategies and calculated properties. Non-reference fields have an additional, established type-property step that can apply calculated properties from their declared simple type; a local field value still wins. Treat this as field transformation behavior, not as a general promise that calculated properties propagate. Test a calculated property for its concrete source and target path.

Labels and transformed documentation properties are not ordinary scalar Profile properties governed by propagated by. JoinedWorkz preserves them on the established explicit-field-include and page-content-reference paths where the source supports them. Do not infer the same behavior for specialization, type, stereotype or methodtype, and do not use a scalar propagation clause to configure documentation inheritance.

CmnDocu is the canonical documentation representation. Compatibility properties such as @description, @title and @summary are projected from that representation for existing generators; they are not a second authoring or propagation mechanism. Base's lookup of an Example through a field's sourceField chain is likewise explicit OpenAPI selection behavior, not Profile property propagation. See OpenAPI documentation and examples.

Property aliases and deprecation metadata are resolved before a propagated value is exposed under its effective property name. The lifecycle and conflict rules are documented in Advanced property lifecycle metadata.

8. Facility author checklist

Before publishing a propagation rule:

• make the property applicable to every required source context and also to a target context when authors must be able to set a local override there;
• choose the narrow positive form when only selected relationships are intended;
• retain the unrestricted form only when all supported relationships are intentional for backward compatibility;
• test both an allowed and a rejected relationship through the transformed Core Model;
• test a local target override;
• test the observable output of each Cartridge that consumes the property; and
• document the property name, value type, propagation relationships and generated effect as part of the Facility's own reference.

Profile syntax controls whether JoinedWorkz transfers a value. It does not by itself define what generated source code, configuration or documentation that value produces.