Design Model structure

Introduction

The API, domain and integration namespaces modeled in the Solution Designer will be reflected by *.yaml files in the directory /src-design in the related Git repository. Each yaml-file has a defined structure which you can find described below.

Design model yaml structures

Note: Within the yaml files there are often links to other items of the project. Those links are using the paths of the items within the /src-design directory to uniquely identify them.

Agent

An agent is described by a *.yaml file in the folder src-design/domain/<namespaceName>/agent where the identifier is used as the file name (e. g. NewOrderCreatedAgent.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v2/agent.schema.json
type *	Enum (of string)	Type of agent
		Supported values:
		- "event"
triggerEventLink *	String	Link to business event that triggers the agent
mappedBusinessEventLinks *	Array of string	Links to business events that are associated with the agent and can be triggered from it
		Can be an empty array
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v2/agent.schema.json
type: event
mappedBusinessEventLinks: []
triggerEventLink: /domain/ord/event/NewOrderCreated
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
comments:
  - text: Some comment
    creationTs: '1687780358190'
    creator: John Doe
documentation:
  schemaVersion: /v1/documentation.schema.json
  fileLink: /domain/cons/agent/NewOrderCreatedAgent.md
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

API Dependency

An API Dependency is consisting out of two yaml files in the folder src-design/integration/<namespaceName>/<apiDependencyName>.

meta.yaml

The meta.yaml contains meta information about the modeled API Dependency.


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v1/apiDependency.schema.json
fileLink	String	Link to the associated spec.yaml containing the API specification
localLookup	Boolean	Indicates whether the API binding should be auto resolved. Usually set to false, when apiBinding is defined
apiBinding	String	JSON string defining values for the API Dependency bindings. NOTE: If "URL" is defined, the URL in the Specification file will be overwritten.
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array

* Mandatory field

Example file:

schemaVersion: /v1/apiDependency.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
fileLink: /integration/petstore/apiDependency/pet/spec
apiBinding: '{ "url": "https://petstore.swagger.io/v2" }'
localLookup: false

spec.yaml

The spec.yaml file contains the uploaded API specification of the API Dependency. It is linked within the meta.yaml file.

Command

A command is described by a *.yaml file in the folder src-design/domain/<namespaceName>/command where the identifier is used as the file name (e. g. CreateOrderCommand.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v2/command.schema.json
type *	Enum (of string)	Type of command
		Supported values:
		- "factory"
		- "instance"
label *	String	Label of the command, used for displaying purposes
shortLabel	String	Short label of the command, used for displaying purposes
notes	String	Further notes describing the command
baseEntityLink *	String	Link to root entity to which the command is associated
inputEntityLink	String	Link to input entity of the command
inputIsEntityList	Boolean	Indicates if input entity is a list or not
mappedBusinessErrorLinks *	Array of string	Links to business errors that are associated with the command and can be thrown from it
		Can be an empty array
mappedBusinessEventLinks *	Array of string	Links to business events that are associated with the command and can be triggered from it
		Can be an empty array
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v2/command.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
label: CreateOrderCommand
type: factory
baseEntityLink: /domain/dom1/entity/OrderEntity
inputEntityLink: /domain/dom1/entity/CreateOrderCommand_Input
inputIsEntityList: false
mappedBusinessErrorLinks:
  - /domain/dom1/error/OrderCreationFailed
mappedBusinessEventLinks:
  - /domain/dom1/event/NewOrderCreated
documentation:
  fileLink: /domain/dom1/command/CreateOrderCommand.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Comment

Comments can be stored at every item during development to leave hints, notes and other information.


Property	Type	Title/Description
text *	String	The comment itself
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item

* Mandatory field

Example:

text: Some comment
creationTs: '1687780358190'
creator: John Doe

Database collection

A database collection is described by a *.yaml file in the folder src-design/domain/<namespaceName>/dbCollection where the identifier is used as the file name (e. g. orders.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v1/dbCollection.schema.json
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array

* Mandatory field

Example file:

schemaVersion: /v1/dbCollection.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012

Documentation

Within each item, which has a documentation possibility, you can find an object that holds several details around the documentation. E.g. creator information or where the acutal documentation content is stored as this is preserved in a separate *.md file.


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be "/v1/documentation.schema.json"
fileLink *	String	Link to the documentation file
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item

* Mandatory field

Example:

fileLink: /domain/dom1/command/MyCommand.md
schemaVersion: /v1/documentation.schema.json
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012

Entity

An entity is described by a *.yaml file in the folders src-design/domain/<namespaceName>/entity or src-design/integration/<namespaceName>/entity where the identifier is used as the file name (e. g. Order.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v3/entity.schema.json
type *	Enum (of string)	Type of entity
		Supported values:
		- "root"
		- "entity"
		- "external"
label *	String	Label of the entity, used for displaying purposes
shortLabel	String	Short label of the entity, used for displaying purposes
notes	String	Further notes describing the entity
isLocallyManaged	Boolean	Whether the entity is locally managed. This means the entity lives within the context of the Input/Output/Payload of a Service/Command/Event
		Default value is false
isAbstract	Boolean	Boolean value indicating if the entity is abstract
		Default value is false
parentLinks	Array of string	Links to entities used as parents of the entity
properties *	Array of Property Mapping	List of properties used to describe the fields of the entity
		Can be an empty array
dbCollectionLink	String	Link to the database collection to which the entity is associated
		Only filled for entities of type root
constructorProperties	Array of Property Mapping	List of properties used to prepare the external entity to reference an external object or call
		Only filled for entities of type external
knownEntityLinks	Array of string	Links to entities that could be possible responses that the External Entity may know about
		Only filled for entities of type external
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v3/entity.schema.json
type: root
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
label: Order Entity
shortLabel: Order
notes: An entity that describes an order
isAbstract: false
isLocallyManaged: false
parentLinks:
  - /domain/dom1/entity/GenericOrder
dbCollectionLink: /domain/dom1/dbCollection/orders
properties:
  - mappingType: value
    isMandatory: true
    propertyDefinitionLink: /domain/dom1/propertyDefinition/orderId
    propertyName: orderId
constructorProperties: []
comments: []
documentation:
  fileLink: /domain/dom1/entity/Order.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Property mapping

Property mappings are used within entities to associate property definitions and entities. Additionally some further information can be stored at the property mapping, which just affects the usage of the property within the entity, but not the property definition itself.


Property	Type	Title/Description
propertyDefinitionLink *	String	Link to the property definition
propertyName *	String	The name of the property in context of the entity
		Can be different from the original identifier in the property definition
isMandatory *	Boolean	Indicates whether the property is defined as a mandatory field or not
mappingType *	Enum (of string)	Mapping type
		Supported values:
		- "value" for all properties that have no range defined
		- "range" (in case of properties with type reference, localEntity or externalEntity)
rangeRestrictionLink	String	Link to entity that restricts the range further
		Has to be a children of the original property range
minValue	String	The minimum value that can be set for the property
		Only for properties of type "currency", "decimal" or "integer"
maxValue	String	The maximum value that can be set for the property
		Only for properties of type "currency", "decimal" or "integer"
minLength	String	The minimum length that the value of the property must have
		Only for text type properties
maxLength	String	The maximum length that the value of the property must have
		Only for text type properties
defaultValue	String	The default value for the property
		Only for text type properties
validationPattern	String	The validation pattern for the property
		Only for text type properties

Example:

propertyDefinitionLink: /domain/dom1/propertyDefinition/orderId
propertyName: orderId
isMandatory: true
mappingType: value
minLength: '1'
maxLength: '26'

Error

An error is described by a *.yaml file in the folders src-design/domain/<namespaceName>/error or src-design/integration/<namespaceName>/error where the identifier is used as the file name (e. g. OrderCancellingFailed.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v2/error.schema.json
errorMessage *	String	Error message
errorDescription	String	Description of the business error
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v2/error.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
errorMessage: Order cancelling failed
errorDescription: The cancelling of one or many orders failed. Please try again
documentation:
  fileLink: /domain/dom1/error/OrderCancellingFailed.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Event

An event is described by a *.yaml file in the folder src-design/domain/<namespaceName>/event where the identifier is used as the file name (e. g. NewOrderCreated.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v3/event.schema.json
type *	Enum (of string)	Type of event
		Supported values:
		- "business"
label *	String	Label of the event, used for displaying purposes
shortLabel	String	Short label of the event, used for displaying purposes
notes	String	Further notes describing the event
topicAlias *	String	Alias of associated topic binding
payloadType	String	Event Payload type
		Supported values:
		- "schema"
		- "entity" (default, but deprecated)
schemaPayloadMetadata	Object of type Schema metadata	Information, which schema is used as payload of the event
		Is empty if payloadType is entity or no payload is used at all
payloadSchemaReferenceId	String	Payload reference id
payloadEntityLink	String	Link to the entity, which is used as payload for the event
		Is empty if payloadType is schema or no payload is used at all
payloadIsEntityList	Boolean	Indicates if payload entity is list or not
		Is empty if payloadType is schema or no payload is used at all
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v3/event.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
type: business
label: New order has been created
shortLabel: Order created
notes: An event that describes that an order has been created
topicAlias: new-order-created-topic
payloadType: Schema
schemaPayloadMetadata:
  artifactId: order-details
  groupId: order
  version: '2'
documentation:
  fileLink: /domain/dom1/event/NewOrderCreated.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Schema metadata

Schema metadata is used within events to describe the necessary information to identify a schema which can be used as event payload.


Property	Type	Title/Description
groupId *	String	Id of apicurio group in which the schema is stored
artifactId *	String	Unique id of the schema, how it is stored in the apicurio registry
version *	String	Used version of the schema

* Mandatory field

Example:

groupId: order
artifactId: order-details
version: '2'

Namespace

An event is described by a *.yaml file in the folders

src-design/api/<namespaceName>/event
src-design/domain/<namespaceName>/event
src-design/integration/<namespaceName>/event where the identifier is used as the file name (e. g. dom1.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v2/namespace.schema.json
type *	Enum (of string)	Type of namespace
		Supported values:
		- "api"
		- "domain"
		- "integration"
label *	String	Label of the namespace, used for displaying purposes
description	String	Description of the namespace, used for displaying purposes
supportedSpec	Enum (of string)	Supported API specification for the API Namespace. Is mandatory if type is "api"
		Supported values:
		- "openApi3.0"
		- "swagger2.0"
host	String	Base path under which the API will be published
		Only if type is "api"
apiTitle	String	Title of the published API
		Only if type is "api"
apiDescription	String	Description of the published API
		Only if type is "api"
apiVersion	String	Version of the published API
		Only if type is "api"
contactName	String	Contact name used in the published API
		Only if type is "api"
contactEmail	String	Contact mail used in the published API
		Only if type is "api"
contactUrl	String	Contact url used in the published API
		Only if type is "api"
licenseName	String	License name used in the published API
		Only if type is "api"
licenseUrl	String	License url used in the published API
		Only if type is "api"
termsOfService	String	Terms of service url used in the published API
		Only if type is "api"
ibmBpmIntegration	Boolean	Describes if this namespace is used for integration with IBM Business Process Management
		Only if type is "api"
ibmApiConnectIntegration	Boolean	Describes if this namespace is used for integration with IBM API Connect
		Only if type is "api"
xIbmName	String	The display name within IBM API Connect
		Only if type is "api"
apiConnectConfigurations	Object of type IBM API Connect Configuration	Configurations to add extensions specific to IBM API Connect
		Only if type is "api"
description	String	Label of the description, used for displaying purposes
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v2/namespace.schema.json
type: domain
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
label: dom1
documentation:
  fileLink: /domain/dom1/dom1.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

IBM API Connect Configuration

IBM API Connect Configuration is used within API namespaces which should be integrated within IBM API Connect. They hold various information to ease the integration.


Property	Type	Title/Description
phase *	String	Used to describe the maturity of the API
		Supported values:
		- "identified"
		- "specified"
		- "realized"
testable *	Boolean	Used to specify whether the API can be tested using the test tool in the Developer Portal
enforced *	Boolean	Used to specify if the API Connect gateway is used to enforce the API
cors *	Object of type IBM API Connect Cors Settings	CORS access control for IBM API Connect
type *	String	Type of API
		Supported values:
		- "rest"

* *Mandatory field

Example:

phase: identified
testable: true
enforced: true
cors:
  enabled: true
type: rest

IBM API Connect Cors Settings

IBM API Connect Cors settings are used within IBM API Connect Configuration to describe the cores settings when integrating with IBM API Connect.


Property	Type	Title/Description
enabled *	Boolean	Used to specify whether CORS access control is used for the API

Example:

enabled: true

Property Definition

A property definition is described by a *.yaml file in the folders src-design/domain/<namespaceName>/propertyDefinition or src-design/integration/<namespaceName>/propertyDefinition where the identifier is used as the file name (e. g. orderId.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v2/propertyDefinition.schema.json
type *	Enum (of string)	Type of property
		Supported values: boolean, currency, date, decimal, externalReference, geoPoint, integer, localEntity, localizedText, reference, selectionElement, text, text/url, text/email, timestamp
label	String	Label of the property, used for displaying purposes
shortLabel	String	Short label of the property, used for displaying purposes
notes	String	Further notes describing the property
isList	Boolean	Indicates if property is a list or not
		Only if type is "localEntity", "reference" or "externalReference"
rangeLink	String	Link to the range entity
		Only if type is "localEntity", "reference" or "externalReference"
decimalPlaces	String	The amount of decimal places specified for the property
		Only if type is "decimal"
selectionElements	Object of type Selection Element	Enumeration elements specified for the property
		Only if type is "selectionElement"

* Mandatory field

Example decimal property rating.yaml:

schemaVersion: /v2/propertyDefinition.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
type: decimal
decimalPlaces: '2'
documentation:
  fileLink: /domain/dom1/propertyDefinition/rating.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Example selection element property orderStatus.yaml:

schemaVersion: /v2/propertyDefinition.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
type: selectionElement
selectionElements:
  new:
    notes: 'Order has status new'
  done:
    notes: 'Order has status done'
  cancelled: {}
documentation:
  fileLink: /domain/dom1/propertyDefinition/orderStatus.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Selection Elements

Selection elements are used within the property definitions of type selectionElement and specify the available keys. Each key can also own notes


Property	Type	Title/Description
<anyKey>	Object	Object holding one property notes for further details

Example:

new:
  notes: 'Order has status new'
done:
  notes: 'Order has status done'
cancelled: {}

Service

A service is described by a *.yaml file in the folders src-design/domain/<namespaceName>/service or src-design/integration/<namespaceName>/service where the identifier is used as the file name (e. g. CancelAllOrders.yaml)


Property	Type	Title/Description
schemaVersion *	Enum (of string)	Item version, describing what kind of item it is
		Must be /v2/service.schema.json
type *	Enum (of string)	Type of service
		Supported values:
		- "domain"
		- "integrationRest"
label *	String	Label of the service, used for displaying purposes
shortLabel	String	Short label of the service, used for displaying purposes
notes	String	Further notes describing the service
inputEntityLink	String	Link to input entity of the service
inputIsEntityList	Boolean	Indicates if input entity is a list or not
outputEntityLink	String	Link to output entity of the service
outputIsEntityList	Boolean	Indicates if output entity is a list or not
mappedBusinessErrorLinks *	Array of string	Links to business errors that are associated with the service and can be thrown from it
		Can be an empty array
mappedBusinessEventLinks *	Array of string	Links to business events that are associated with the service and can be triggered from it
		Can be an empty array
sagaDetails	Object of type Saga details	Saga related details if service is used as orchestrator or participant within a saga
creationTs *	String	Creation timestamp in milliseconds
creator *	String	Creator of the item
creatorId	String	ID of the creator of the item
comments *	Array of Comment	List of comments, which were added to the item during development
		Can be an empty array
documentation *	Object of type Documentation	Documentation information

* Mandatory field

Example file:

schemaVersion: /v2/service.schema.json
comments: []
creationTs: '1687780358190'
creator: John Doe
creatorId: 12345678-1234-1234-1234-123456789012
label: CancelAllOrders Service
shortLabel: Cancel orders
type: domain
inputEntityLink: /domain/dom1/entity/Order
inputIsEntityList: true
outputEntityLink: /domain/dom1/entity/CancelOrderCommand_Input
outputIsEntityList: false
mappedBusinessErrorLinks:
  - /domain/dom1/error/OrderCancellingFailed
mappedBusinessEventLinks:
  - /domain/dom1/event/OrderCancelled
documentation:
  fileLink: /domain/dom1/command/CancelAllOrders.md
  schemaVersion: /v1/documentation.schema.json
  creationTs: '1687780358190'
  creator: John Doe
  creatorId: 12345678-1234-1234-1234-123456789012

Saga details

Saga details is used within services to describe the necessary information when the service is chosen to be used in a saga (either as orchestrator or participant)


Property	Type	Title/Description
type *	Enum (of string)	Type of saga item
		Supported values:
		- "orchestrator"
		- "participant"
propagationLevel *	Enum (of string)	Saga propagation level
		Supported values:
		- "required"
		- "requires_new"
		- "mandatory"
		- "supports"
		- "not_supported"
		- "never"
completionMode *	Enum (of string)	Saga completion mode
		Supported values:
		- "auto"
		- "manual"
hasOnCompensateMethod *	Boolean	Indicates whether an `onCompensate` method should be autogenerated
		Default value is "false"
hasOnCompleteMethod *	Boolean	Indicates whether an `onComplete` method should be autogenerated
		Default value is "false"
mappedParticipantLinks	Array of string	Array of links to participants that can be called in the orchestrator
		Only if type is *"orchestrator"
options	Object	Option expressions as key value pair, provided as additional information within the implementation
		Only if type is *"participant"

* Mandatory field

Orchestrator example:

type: orchestrator
propagationLevel: 'required'
completionMode: 'manual'
hasOnCompensateMethod: true
hasOnCompleteMethod: false
mappedParticipantLinks:
  - /domain/dom1/service/SagaParticipantService1
  - /domain/dom1/service/SagaParticipantService2

Participant example:

type: participant
propagationLevel: 'required'
completionMode: 'manual'
hasOnCompensateMethod: true
hasOnCompleteMethod: false
options:
  opt1: 'value1'
  opt2: 'value2'