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 = "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β
"""
Send Email
"""
# ...
Example as string literalβ
"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 failureunsafe
- The use-case may result in a change on the service, so any attempt to retry a use-case may result in unintended changesidempotent
- 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.
"""
Retrieve Shipment Status
Get the current shipment status.
"""
usecase ShipmentInfo safe {
# ...
}
Here is the same example with single double-quotes.
"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β
# ...
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 withtimestamp
andstatusText
- 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β
# ...
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
# ...
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
.
model WeatherInformation {
airTemperature
atmosphericPressure
}
Alias modelβ
Models can be aliased by using a Named Model and referencing an existing 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
.
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.
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.
model WeatherHistory [ WeatherInformation ]
Enum Modelβ
model Channel enum {
sms
whatsapp
viber
}
The enum names can also have a value associated with them.
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
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 |
.
model WeatherData WeatherHistory | WeatherInformation
Primitivesβ
Comlink has support for primitives that can be used as field specifications.
string
boolean
number