2.1 KMeta

A KMeta text is a metamodel. It defines types, and each type has properties, which hold values, and relations, which lead to objects of other types. A file has the extension .kmeta. The grammar of the language is src/main/antlr/io/karpfen/dsl/grammar/kmeta/Kmeta.g4 in the karpfen-dsl-tools repository.

2.1.1 Types#

A type starts with the keyword type, its name and a description, both as strings, and a body in braces. The body holds the rules of the type, one prop, has or knows per rule, in any order. A body may be empty.

type "Switch" "A wall switch" {
}

The name identifies the type. Models and state machines refer to it, and names are case sensitive. The description is text for the reader. It is required, but it may be the empty string "". A text defines one type or more. Between the description and the body, a type may name the state machine its objects behave after, see 2.1.8 Behaviour of a type.

2.1.2 Properties#

prop("key", "type") gives a type a property: a value of one of the primitive types string, number and boolean. The type names are written in lower case.

type "Bulb" "A light bulb" {
    prop("maxWatts", "number")
    prop("watts", "number")
    prop("lit", "boolean")
}

A number is a decimal number, such as 40 or 0.5. A boolean is true or false. A string is any text. How a model writes these values is described in 2.2.3 Property values.

2.1.3 Relations#

A relation leads from an object to an object of another type, or of the same type. There are two kinds.

has("key", "Type") embeds an object. The embedded object belongs to the object that holds it: in a model it is written inside its owner, and it exists once, at that place. knows("key", "Type") refers to an object that is embedded somewhere else in the model. A model names that object by its key.

type "Bulb" "A light bulb" {
    prop("watts", "number")
}
type "Switch" "A wall switch" {
    prop("position", "string")
}
type "Lamp" "A lamp with a bulb, wired to a switch" {
    has("bulb", "Bulb")
    knows("control", "Switch")
}
type "Room" "The room the lamp stands in" {
    has("lamp", "Lamp")
    has("switch", "Switch")
}

Here the bulb is part of the lamp, and the lamp refers to the switch, which is part of the room. The target type of a relation must be a type of the metamodel. It may be defined before or after the type that uses it.

2.1.4 Lists#

list("type") in place of the type makes a property or a relation hold a list. A list keeps the order of its elements and may be empty.

type "Lamp" "A lamp" {
    prop("mode", "string")
}
type "Switch" "A wall switch" {
    prop("presses", list("string"))
    knows("lamps", list("Lamp"))
}
type "Room" "A room with several lamps" {
    has("lamps", list("Lamp"))
    has("switch", "Switch")
}

presses holds a list of strings, lamps of the room embeds a list of lamps, and lamps of the switch refers to a list of lamps. A property or relation without list holds at most one value.

2.1.5 The root type#

The last type of a text is the root type of the metamodel. In the examples of 2.1.3 and 2.1.4 it is Room. Write the type of the root object of the model last. The readers do not check that the root object of a model has the root type.

2.1.6 Rules of a metamodel#

A metamodel must keep these rules. 2.4.3 KMeta lists the code of each problem.

  • The text defines at least one type.
  • No two types have the same name.
  • No two rules of one type have the same key, whether they are properties, relations or both.
  • A prop has the type string, number or boolean, written in lower case, or a list of one of them.
  • A has or knows names a type of the metamodel, not a primitive type.
  • A behaves after names an attachable state machine of the project that lists the type, and stands only in the domain metamodel. The verifier of a project checks this rule, since it needs the state machines.

Every property and relation is optional in a model. KMeta has no default values, no inheritance between types and no numbers of elements other than one and a list.

2.1.7 Event definitions#

The events of a project are defined in a second KMeta text, the event metamodel. Each type of it is one event: the name of the type is the name of the event, and the properties and relations of the type are the payload the event carries. An event without payload is a type with an empty body.

// The events of the lamp example.
type "press" "Presses the wall switch" {
}
type "dim" "Turns the dimmer one step: brighter when bright is true, dimmer when it is false" {
    prop("bright", "boolean")
}
type "smash" "Breaks the lamp" {
}

The event metamodel names no domain. A state machine names the domain together with the event, as in EVENT("switch", "dim"), and reads the payload as event->bright, see 2.3.5 Events.

The event metamodel is read with the types of the domain metamodel at hand. A payload may therefore embed or refer to a domain type without defining it again, for example has("position", "Point") in an event type when Point is a type of the domain metamodel. The event types do not become part of the domain metamodel. The last type of an event metamodel is its root type, which has no meaning for events.

2.1.8 Behaviour of a type#

behaves after "name" between the description and the body of a type gives every object of the type an instance of the attachable state machine of that name: each object of the model when a run starts, and each object that a rule of a state machine creates. The keywords are written in lower case.

type "Bulb" "A light bulb" behaves after "glowing" {
    prop("watts", "number")
    prop("lit", "boolean")
}

The state machine must be attachable to the type, as in STATEMACHINE "glowing" ATTACHABLE TO "Bulb", see 2.3.1 The state machine. Types without the clause have no state machine of their own unless a run or a rule attaches one. An event type cannot have the clause. 2.3.11 State machine management and lifecycle explains when to use it.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.