Skip to main content

Comlink Profile Reference

Comlink Profile is a format for describing business capabilities as use-cases apart from implementation details.

Profile details​

Name​

The name property defines the profile name. It can be a basic profile name or a scoped name. To scope a profile, add scope-name/ before profile name, for example: communication/send-email.

Version​

The version property specifies the profile version following SemVer.

Example​

Name and version example
name = "communication/send-email"
version = "1.1.1"

# ...

Description​

A profile description goes at the top of the profile and is either a string literal with a single double-quote or a block string literal with three double-quotes.

Example as block string literal​

Block string literal description example
"""
Send Email
"""

# ...

Example as string literal​

String literal description example
"Send Email"

# ...

Use-cases​

The use-case is a task that needs to be done to support a business need. Use-cases have inputs and outputs similar to functions in code. They provide a higher-level abstraction that can separate the business need from the implementation as defined in a Comlink Map.

Safety​

You can define a safety level for a use-case. This safety level follows the use-case name and is optional. By default it is safe. The safety level can be:

  • safe (default) - The use-case doesn't result in server-side changes, so the client can retry the use-case when there's a failure
  • unsafe - The use-case may result in a change on the service, so any attempt to retry a use-case may result in unintended changes
  • idempotent - The client can execute the use-case multiple times while the server will only process it once, so clients may safely retry failures

This is informational for the tooling to know how it should handle retrying failures. For more information, see Understanding Idempotency and Safety in API Design.

Description​

Use-cases can have descriptions similar to a Profile Description. It can be either single double-quotes or three double-quotes and goes directly before the use-case declaration. Both single quotes and triple double-quotes descriptions can contain both title and a body of the description. The single double-quote variant has the title on the same line as quote.

Example​

This example shows a title of "Retrieve Shipment Status" and a description of "Get the current shipment status" using triple double-quotes.

Use-case triple double-quote description
"""
Retrieve Shipment Status
Get the current shipment status.
"""
usecase ShipmentInfo safe {
# ...
}

Here is the same example with single double-quotes.

Use-case sing double-quote description
"Retrieve Shipment Status
Get the current shipment status."
usecase ShipmentInfo safe {
# ...
}

Inputs​

The inputs define the inputs needed to perform the use-case. The inputs MUST be defined as an Object Model.

Example​

Inputs example
# ...

usecase ShipmentInfo safe {
input {
trackingNumber! string!
carrier string!
}

result {
carrier string!
status! string
origin string
destination string
events! [{
timestamp! string
statusText! string
}]
estimatedDeliveryDate
}

error {
title! string
detail string
}
}

Some notes about this example and its fields.

  • The estimatedDeliveryDate field is untyped
  • The events field is an array of objects with timestamp and statusText
  • Fields marked with an exclamation mark are required as in trackingNumber! string
  • Field types marked with an exclamation mark are non-null as in carrier string!

Result​

Example​

Result example
# ...

usecase ShipmentInfo safe {
input {
trackingNumber! string!
carrier string!
}

result {
carrier string!
status! string
origin string
destination string
events! [{
timestamp! string
statusText! string
}]
estimatedDeliveryDate
}

error {
title! string
detail string
}
}

Error​

The use-case can define an optional error which will be returned when the use-case execution fails.

Example​

This example

Error example
# ...

usecase ShipmentInfo safe {
input {
trackingNumber! string!
carrier string!
}

result {
carrier string!
status! string
origin string
destination string
events! [{
timestamp! string
statusText! string
}]
estimatedDeliveryDate
}

error {
title! string
detail string
}
}

Models​

Any input, result, or error can use models directly or reference a named model. The examples throughout this reference have used inline models.

Named models​

This shows a Named Model example. This model can be referenced in other models and in the use-case inputs, result, and error.

Named model
model WeatherInformation {
airTemperature
atmosphericPressure
}

Alias model​

Models can be aliased by using a Named Model and referencing an existing model.

Alias model
model MyWeatherInformation WeatherInformation

Field definitions​

Field definitions describe the name, specification, and whether or not the field is required. Field names may be documented with single or triple quotes. The field name is the only required part of a field definitionβ€”types are optional.

The defaults for a field definition are:

  • Fields are optional by default. Add a ! to the field name to make it required.
  • Field specifications are of type string by default.
  • Field specifications are nullable by default. Add a ! to the field specification to make it non-nullable.
warning

Marking a field as non-nullable doesn't make it required. To make the field required and non-nullable, you must add ! after both the field's name and type.

Field description​

Individual fields can be described the same way as the profile can. This example shows two fields with descriptions, the trackingNumber field using triple double-quotes and the carrier using single double-quotes.

usecase ShipmentInfo safe {
input {
"""
Shipment tracking number
Identifier of shipment
"""
trackingNumber

"Carrier
Shipment carrier identification to narrow down the results"
carrier string!
}
}

Field name​

The field name is the first part listed in a field definition. There are two field definitions below with field names airTemperature, and atmosphericPressure.

Named model
model WeatherInformation {
airTemperature
atmosphericPressure
}

Field specification​

The field specification defines the type of the field which is a Model Definition. By default it is nullable. Add a ! to make it a non-null field.

Model definitions​

Object Model​

Object Models include a list of field definitions and are enclosed by curly brackets { and }. They correspond to an Object in JavaScript or Dictionary in Python. Refer to the field definitions above to see how to define field definitions in an Object Model.

Named model
model WeatherInformation {
airTemperature
atmosphericPressure
}

List Model​

List Models include a list of models enclosed by a [ and ]. They correspond to an Array in JavaScript or List in Python.

List model
model WeatherHistory [ WeatherInformation ]

Enum Model​

Enum model
model Channel enum {
sms
whatsapp
viber
}

The enum names can also have a value associated with them.

Enum model with values
model Unit enum {
"Degrees of Celsius"
C = 'celsius'

"Degrees of Fahrenheit"
F = 'fahrenheit'
}

Lastly, enums can be separated by newlines as shown above or with commas

Enum model with commas
model Channel enum { sms, whatsapp, viber }

Union Model​

Union Models are used to define a model that might be one of the referenced models. Model references are separated by a |.

Union model
model WeatherData WeatherHistory | WeatherInformation

Primitives​

Comlink has support for primitives that can be used as field specifications.

  • string
  • boolean
  • number

Additional Resources​