Comlink Profile

Version 2023.01.16

Introduction

/Typed semantic profile/

/Use‐case description language/

Comlink Profile is a simple format for describing application use‐cases. It enables you to describe the business behavior of an application without the need to go into detail of implementation.

The profile language was designed with distributed systems applications in mind but can be used for describing any use cases or even for modeling entire domains using the DDD approach.

Unlike other formats (E.g. Gherkin) Profile does not support the description of actors, roles, or pre‐requisites.

Contrary to pure semantic profiles (e.g. ALPS) Superface Profile allows adding a type overlay for defined models to allow for the creation of rich developer experiences.

By convention, one profile file should comprise of one use case (E.g. “Get weather” or “Make payment”).

When submitted to a profile store, the profile must be assigned a globally unique identifier in the form URL (preferably de‐reference‐able).

1Profile Document

Example № 1name = "meteo/get-weather"
version = "1.0.0"

usecase GetWeather {
  ...
}

Example № 2name = "meteo/get-weather"
version = "1.0.0"

usecase GetWeather {
  ...
}

model WeatherInformation {
  ...
}

Example № 3name = "meteo/get-weather"
version = "1.0.0"

usecase GetWeather {
  ...
}

model WeatherInformation {
  ...
}

field location Place

2Description

Description
"String"
"""String"""

Any definition in the profile document can have a preceding human‐readable description. Any string literal or block string literal preceding a definition is treated as a description.

Example № 4"Use-case description"
usecase GetWeather {
  ...
}

Example № 5"""
Retrieve Weather Information

Use-case description
"""
usecase GetWeather {
  ...
}

3Use-case

Safety
safeunsafeidempotent
Example № 6usecase GetWeather {
  input {
    location
    units
  }

  result {
    airTemperature
    atmosphericPressure
  }
}

Example № 7"""
Send Message

Send single conversation message
"""
usecase SendMessage unsafe {
  input {
    "To
      recepient of the message"
    to

    "From
      sender of the message"    
    from
    
    channel

    "Text 
      the text of the message"
    text
  }

  result {
    messageId
  }

  async result {
    messageId
    deliveryStatus
  }

  error {
    problem
    detail
    instance
  }
}

4Models

4.1Named Model

4.2Model Definition

4.2.1Object Model

Example № 8model WeatherInformation {
  airTemperature
  atmosphericPressure
}

The field definitions of an object model type MUST be separated by a newline or comma , :

Example № 9// Newline-separated
{
  airTemperature
  atmosphericPressure
}

// Comma-separated
{ airTemperature, atmosphericPressure }

4.2.2List Model

Example № 10model WeatherHistory [ WeatherInformation ]

4.2.3Enum Model

EnumElementValue
=ScalarValue
Example № 11model Channel enum {
  sms
  whatsapp
  viber
}

Example № 12model Unit enum {
  "Degrees of Celsius"
  C = 'celsius'

  "Degrees of Fahrenheit"
  F = 'fahrenheit'
}

Example № 13model Values enum {
  byte = 8
  kiloByte = 1024
  fourKiloBytes = 4096
}

Example № 14// Newline-separated
enum {
  sms
  whatsapp
  viber
}

// Comma-separated
enum { sms, whatsapp, viber }

4.2.4Union Model

Example № 15model WeatherData WeatherHistory | WeatherInformation

4.2.5Alias Model

Example № 16model MyWeather WeatherInformation

4.2.6Scalar Model

Example № 17model Place

Scalar models can have a type overlay using one of the built‐in primitive types:

Example № 18model Place string

5Fields

5.1Named Field

5.2Field Definition

5.2.1Required field

By default all fields are optional. To declare field that is required use RequiredField after FieldName

Example № 19model User {
  name! string      // the field "name" is required (but can be None)
  email string      // the field "email" is optional
}

6Example

7Literal

7.2None Literal

7.3Primitive Literal

DigitBaseTen
/[0-9]/
DigitBaseTwo
/[0-1]/
DigitBaseSixteen
/[0-9a-fA-F]/
BooleanLiteral
true|false

7.4Object Literal

LHS
VariableNameVariableKeyPathObjectVariablelistopt

7.5Array Literal

8Types

8.1Primitive types

ScalarType
booleanstringnumber

8.2Required value

By default all values are optional. To declare value that cannot be None use RequiredValue after ModelDefinition

Example № 20model User {
  name string!      // value of name cannot be None
  email string      // value of email can be None
}

Example № 21usecase Example {
  result string! // result must be of type string
}

9Language

9.1Source text

SourceCharacter
/[\u0009\u000A\u000D\u0020-\uFFFF]/

9.1.1Comments

Example № 22// This is a comment

9.1.2Line Terminators

LineTerminator
New Line (U+000A)
Carriage Return (U+000D)New Line (U+000A)
Carriage Return (U+000D)New Line (U+000A)

9.2Common Definitions

9.2.1Identifier

Identifier
/[_A-Za-z][_0-9A-Za-z]*/

9.2.2Profile Identifier

DocumentNameIdentifier
/[a-z][a-z0-9_-]*/

Identifier of a profile regardless its version.

Example № 23character-information

Example № 24starwars/character-information

9.2.3Full Profile Identifier

Fully disambiguated identifier of a profile including its exact version.

Example № 25character-information@2.0.0

Example № 26starwars/character-information@1.1.0

9.2.4Map Profile Identifier

Profile identifier used in maps does not include the patch number.

Example № 27starwars/character-information@1.1

9.2.5Provider Identifier

9.2.6Service Identifier

Service identifier form provider’s definition. Generally used for specifying a service base (host) URL.

9.2.7URL Value

URLValue
"URL"

9.2.8Security Scheme Identifier

References the security scheme found within a provider definition.

9.2.9String Value

9.2.10Integer Value

IntegerValue
/[0-9]+/

§Index

  1. AliasModel
  2. ArrayItemContinued
  3. ArrayItems
  4. ArrayLiteral
  5. AsyncResult
  6. BooleanLiteral
  7. CharacterLiteral
  8. ComlinkLiteral
  9. Comment
  10. CommentChar
  11. Description
  12. DigitBaseEight
  13. DigitBaseSixteen
  14. DigitBaseTen
  15. DigitBaseTwo
  16. DocumentNameIdentifier
  17. EnumElement
  18. EnumElementName
  19. EnumElementValue
  20. EnumModel
  21. Error
  22. EscapedCharacter
  23. Example
  24. ExampleError
  25. ExampleInput
  26. ExampleOutput
  27. ExampleResult
  28. FieldDefinition
  29. FieldName
  30. FieldSpecification
  31. FullProfileIdentifier
  32. Identifier
  33. Input
  34. IntegerValue
  35. KeyValueAssignment
  36. LHS
  37. LineTerminator
  38. ListModel
  39. MajorVersion
  40. MapProfileIdentifier
  41. MinorVersion
  42. ModelDefinition
  43. ModelName
  44. ModelReference
  45. ModelSpecification
  46. NamedField
  47. NamedModel
  48. NoneLiteral
  49. NumberLiteral
  50. NumberLiteralDigits
  51. NumberLiteralFloat
  52. NumberLiteralInteger
  53. NumberLiteralIntegerBaseEight
  54. NumberLiteralIntegerBaseSixteen
  55. NumberLiteralIntegerBaseTen
  56. NumberLiteralIntegerBaseTwo
  57. NumberSign
  58. ObjectLiteral
  59. ObjectModel
  60. PatchVersion
  61. PrimitiveLiteral
  62. ProfileDocument
  63. ProfileIdentifier
  64. ProfileName
  65. ProfileScope
  66. ProfileVersion
  67. ProviderIdentifier
  68. RequiredField
  69. RequiredValue
  70. Result
  71. Safety
  72. ScalarModel
  73. ScalarType
  74. SecuritySchemeIdentifier
  75. SemanticVersion
  76. ServiceIdentifier
  77. SourceCharacter
  78. StringCharacter
  79. StringLiteral
  80. StringValue
  81. URLValue
  82. UnionModel
  83. UnionModelReferenceList
  84. Usecase
  85. UsecaseName
  86. VariableKeyPath
  87. VariableName
Comlink Profile
  1. 1Profile Document
  2. 2Description
  3. 3Use-case
  4. 4Models
    1. 4.1Named Model
    2. 4.2Model Definition
      1. 4.2.1Object Model
      2. 4.2.2List Model
      3. 4.2.3Enum Model
      4. 4.2.4Union Model
      5. 4.2.5Alias Model
      6. 4.2.6Scalar Model
  5. 5Fields
    1. 5.1Named Field
    2. 5.2Field Definition
      1. 5.2.1Required field
  6. 6Example
  7. 7Literal
    1. 7.1Comlink Literal
    2. 7.2None Literal
    3. 7.3Primitive Literal
    4. 7.4Object Literal
    5. 7.5Array Literal
  8. 8Types
    1. 8.1Primitive types
    2. 8.2Required value
  9. 9Language
    1. 9.1Source text
      1. 9.1.1Comments
      2. 9.1.2Line Terminators
    2. 9.2Common Definitions
      1. 9.2.1Identifier
      2. 9.2.2Profile Identifier
      3. 9.2.3Full Profile Identifier
      4. 9.2.4Map Profile Identifier
      5. 9.2.5Provider Identifier
      6. 9.2.6Service Identifier
      7. 9.2.7URL Value
      8. 9.2.8Security Scheme Identifier
      9. 9.2.9String Value
      10. 9.2.10Integer Value
  10. §Index