Enumerations

An enumeration defines a fixed set of named values. The CMN grammar provides the declaration and value syntax; stereotypes and properties are supplied by the selected profile.

1. Declaration syntax

[description] [abstract] enum [<stereotypes>] Name ["Label"]
    [(specialization of | extends) BaseEnum]
    [property ...] {
        VALUE [: literal] [property ...]
        ...
    }

Example:

package com.example.customer

import org.joinedworkz.facilities.common.base

platform Base

/** Lifecycle of a customer account. */
enum AccountStatus "Account status" {
    ACTIVE: 'A'
    SUSPENDED: 'S'
    CLOSED: 'C'
}

ACTIVE, SUSPENDED, and CLOSED are the CMN names. The literal after : is optional. Properties may follow both the enumeration declaration and each value, but their names and meaning must be defined by the selected profile.

2. Specialization

Both specialization of and extends express a parser relationship to a base enumeration:

package com.example.customer

enum BasicStatus {
    ACTIVE
    INACTIVE
}

enum DetailedStatus extends BasicStatus {
    SUSPENDED
}

JoinedWorkz does not transfer the base-enumeration reference or inherit its values into the canonical enumeration. Propagatable profile properties or stereotypes can still be resolved from the relationship. Do not use this syntax to assume value or target-language inheritance.

3. Stereotypes, labels, and abstract declarations

The grammar also permits stereotype specifications, labels, descriptions, and abstract:

package com.example.shared

import org.joinedworkz.facilities.common.base

platform Base

abstract enum<integer> NumericState "Numeric state" {
    UNKNOWN: 0
}

The grammar also permits a stereotype specification between enum and the name. Only use a stereotype that the selected profile declares as applicable to enumerations. The abstract marker is not transferred to the canonical enumeration and is therefore not a reliable generator signal. Literal values and supported stereotypes remain available to facility cartridges. See Common declaration syntax for the shared notation.

4. Values and properties

An enumeration literal may be:

• an integer or decimal number;
• a quoted string;
• true or false;
• undefined;
• a reference to another model element.

This list describes accepted CMN property-value syntax, not the values accepted by every property. A profile can restrict a property to a specific type or set of values.

5. Integer-coded enumerations

The Base profile makes the integer stereotype available to enumerations:

enum<integer> SetupType {
    NONE: 10
    NP:   20
    JP:   30
}

Every value declared in an integer enumeration requires an explicit integer code after :. Codes must be unique within that enumeration. They do not have to be contiguous or positive.

The value name and its numeric code belong to different contracts:

• NONE, NP, and JP are the enumeration values used by CMN, JSON and OpenAPI;
• 10, 20, and 30 are explicit mapped values that supporting target platforms can use for persistence or another external representation.

Changing a name changes the public enumeration value. Changing a code changes the mapped-value contract even when the public name remains unchanged. Treat either change according to the consumers of that contract.

6. Facility and generator semantics

The declaration and value forms on this page are CMN grammar syntax. The target-language representation remains a facility concern. See the Java facility for the generated Java mapping methods and SpringBoot profile and canonical modeling for the JPA persistence contract. The stable SpringBoot example exercises both the public string representation and the database code; see Build a CRUD backend.