Comlink Profile

Version 2022.03.07

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 fields

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 null)
  email string      // the field "email" is optional
}

5.2.2Non-null field value

By default all fields are nullable. To declare field that can be null use NonNullField after FieldSpecification

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

6Example

7Literal

7.2Primitive Literal

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

7.3Object Literal

LHS
VariableNameVariableKeyPathObjectVariablelistopt

7.4Array Literal

8Types

8.1Primitive types

ScalarType
booleanstringnumber

9Language

9.1Source text

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

9.1.1Comments

Example № 21// 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 № 22character-information

Example № 23starwars/character-information

9.2.3Full Profile Identifier

Fully disambiguated identifier of a profile including its exact version.

Example № 24character-information@2.0.0

Example № 25starwars/character-information@1.1.0

9.2.4Map Profile Identifier

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

Example № 26starwars/character-information@1.1

9.2.5Provider Identifier

9.2.6URL Value

URLValue
"URL"

9.2.7Security Scheme Identifier

References the security scheme found within a provider definition.

9.2.8String Value

9.2.9Integer Value

IntegerValue
/[0-9]+/

§Index

  1. AliasModel
  2. ArrayItemContinued
  3. ArrayItems
  4. ArrayLiteral
  5. AsyncResult
  6. BooleanLiteral
  7. ComlinkLiteral
  8. Comment
  9. CommentChar
  10. Description
  11. DigitBaseEight
  12. DigitBaseSixteen
  13. DigitBaseTen
  14. DigitBaseTwo
  15. DocumentNameIdentifier
  16. EnumElement
  17. EnumElementName
  18. EnumElementValue
  19. EnumModel
  20. Error
  21. EscapedCharacter
  22. Example
  23. ExampleError
  24. ExampleInput
  25. ExampleOutput
  26. ExampleResult
  27. FieldDefinition
  28. FieldName
  29. FieldSpecification
  30. FullProfileIdentifier
  31. Identifier
  32. Input
  33. IntegerValue
  34. KeyValueAssignment
  35. LHS
  36. LineTerminator
  37. ListModel
  38. MajorVersion
  39. MapProfileIdentifier
  40. MinorVersion
  41. ModelDefinition
  42. ModelName
  43. ModelReference
  44. ModelSpecification
  45. NamedField
  46. NamedModel
  47. NonNullField
  48. NumberLiteral
  49. NumberLiteralDigits
  50. NumberLiteralFloat
  51. NumberLiteralInteger
  52. NumberLiteralIntegerBaseEight
  53. NumberLiteralIntegerBaseSixteen
  54. NumberLiteralIntegerBaseTen
  55. NumberLiteralIntegerBaseTwo
  56. NumberSign
  57. ObjectLiteral
  58. ObjectModel
  59. PatchVersion
  60. PrimitiveLiteral
  61. ProfileDocument
  62. ProfileIdentifier
  63. ProfileName
  64. ProfileScope
  65. ProfileVersion
  66. ProviderIdentifier
  67. RequiredField
  68. Result
  69. Safety
  70. ScalarModel
  71. ScalarType
  72. SecuritySchemeIdentifier
  73. SemanticVersion
  74. SourceCharacter
  75. StringCharacter
  76. StringValue
  77. URLValue
  78. UnionModel
  79. UnionModelReferenceList
  80. Usecase
  81. UsecaseName
  82. VariableKeyPath
  83. 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 fields
      2. 5.2.2Non-null field value
  6. 6Example
  7. 7Literal
    1. 7.1Comlink Literal
    2. 7.2Primitive Literal
    3. 7.3Object Literal
    4. 7.4Array Literal
  8. 8Types
    1. 8.1Primitive types
  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.6URL Value
      7. 9.2.7Security Scheme Identifier
      8. 9.2.8String Value
      9. 9.2.9Integer Value
  10. §Index