Model Definitions in AaC

The AaC model root key is used to represent the components of a system. These, for example, can be the services in a system following a Microservice Architecture (MSA) design.

In its most basic form, a model must have a name that distinguishes it from other AaC definitions. At the same time, however, a model that defines nothing more than a name should be treated as incomplete unless the intention is to represent external components or actors.

It is recommended to include behavior definitions for each model to allow users and the AaC package to understand the component as part of the system. Some questions we can answer for models with defined behaviors are:

1. What does the component do?

2. What inputs does it expect?

3. What outputs can the system or other components expect from this component?

Defining Systems Through Model Composition

Whether your system is a monolith or a collection of microservices, the model root key is used to represent how components fit together as part of the system and what those components do as part of the system.

To compose a system from individual components, one specifies additional models in the system model’s components field.

model:
  name: AlarmClock
  description: A simple alarm clock
  components:
    - name: clock
      model: Clock
    - name: timer
      model: ClockTimer
    - name: alarm
      model: ClockAlarm
  behavior:
    - name: setAlarm
      description: Set the alarm timer
      input:
        - name: targetTime
          type: Timestamp
      acceptance:
        - name: Modify Timer State
          scenarios:
            - name: Set timer
              given:
                - The alarm timer is not set
              when:
                - The user sets the alarm timer
              then:
                - The alarm is triggered when the clock reaches the specified time
            - name: Update timer
              given:
                - The alarm timer is set
              when:
                - The user sets the alarm timer
              then:
                - The alarm is triggered when the clock reaches the specified time

Defining System Behavior In Models

Each model should define one, or more, behaviors that describe the component’s behaviors. These behaviors include a description of inputs, outputs, and scenarios that show how the model interacts with different components in the

model:
  name: AlarmClock
  description: A simple alarm clock
  components:
    - name: clock
      model: Clock
    - name: timer
      model: ClockTimer
    - name: alarm
      model: ClockAlarm
  behavior:
    - name: setAlarm
      description: Set the alarm timer
      input:
        - name: targetTime
          type: Timestamp
      acceptance:
        - name: Modify Timer State
          scenarios:
            - name: Set timer
              given:
                - The alarm timer is not set
              when:
                - The user sets the alarm timer
              then:
                - The alarm is triggered when the clock reaches the specified time
            - name: Update timer
              given:
                - The alarm timer is set
              when:
                - The user sets the alarm timer
              then:
                - The alarm is triggered when the clock reaches the specified time

A behavior can also have any combination of inputs and outputs.

Additionally, the action of every behavior is represented by the scenario structure. Each scenario describes necessary pre-conditions (given), triggers (when), and post-conditions (then) for the behavior.

model:
  name: AlarmClock
  description: A simple alarm clock
  components:
    - name: clock
      model: Clock
    - name: timer
      model: ClockTimer
    - name: alarm
      model: ClockAlarm
  behavior:
    - name: setAlarm
      description: Set the alarm timer
      input:
        - name: targetTime
          type: Timestamp
      acceptance:
        - name: Modify Timer State
          scenarios:
            - name: Set timer
              given:
                - The alarm timer is not set
              when:
                - The user sets the alarm timer
              then:
                - The alarm is triggered when the clock reaches the specified time
            - name: Update timer
              given:
                - The alarm timer is set
              when:
                - The user sets the alarm timer
              then:
                - The alarm is triggered when the clock reaches the specified time

External Models

An External Model is a model that does not include an Acceptance Scenario. These types of models are used to create simplified interfaces representing external components or actors. A typical use case for an External Model is to represent a user or external messenger that is not managed by AaC. It allows you to quickly create models without having to fully implement them.

Bellow is an example External Model.

model:
  name: Person
  description: A representation of users/people external to the alarm clock system.

External Models can be referenced, created, and used the same as internal models.

Defining System State In Models

Pending an accurate model representation and sufficient implementation of state within models, this section will not be covered yet.