Comlink Profile

Current Working Draft

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
}

6Types

6.1Primitive types

ScalarType
booleanstringnumber

7Language

7.1Source text

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

7.1.1Comments

Example № 21// This is a comment

7.1.2Line Terminators

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

7.2Common Definitions

7.2.1Identifier

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

7.2.2Profile Identifier

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

Identifier of a profile regardless its version.

Example № 22character-information

Example № 23starwars/character-information

7.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

7.2.4Map Profile Identifier

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

Example № 26starwars/character-information@1.1

7.2.5Provider Identifier

7.2.6Service Identifier

7.2.7URL Value

URLValue
"URL"

7.2.8Security Scheme Identifier

References the security scheme found within a provider definition.

7.2.9String Value

7.2.10Integer Value

IntegerValue
/[0-9]+/

§Index

  1. AliasModel
  2. AsyncResult
  3. Comment
  4. CommentChar
  5. Description
  6. DocumentNameIdentifier
  7. EnumElement
  8. EnumElementName
  9. EnumElementValue
  10. EnumModel
  11. Error
  12. EscapedCharacter
  13. FieldDefinition
  14. FieldName
  15. FieldSpecification
  16. FullProfileIdentifier
  17. Identifier
  18. Input
  19. IntegerValue
  20. LineTerminator
  21. ListModel
  22. MajorVersion
  23. MapProfileIdentifier
  24. MinorVersion
  25. ModelDefinition
  26. ModelName
  27. ModelReference
  28. ModelSpecification
  29. NamedField
  30. NamedModel
  31. NonNullField
  32. ObjectModel
  33. PatchVersion
  34. ProfileDocument
  35. ProfileIdentifier
  36. ProfileName
  37. ProfileScope
  38. ProfileVersion
  39. ProviderIdentifier
  40. RequiredField
  41. Result
  42. Safety
  43. ScalarModel
  44. ScalarType
  45. SecuritySchemeIdentifier
  46. SemanticVersion
  47. ServiceIdentifier
  48. SourceCharacter
  49. StringCharacter
  50. StringValue
  51. URLValue
  52. UnionModel
  53. UnionModelReferenceList
  54. Usecase
  55. UsecaseName
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. 6Types
    1. 6.1Primitive types
  7. 7Language
    1. 7.1Source text
      1. 7.1.1Comments
      2. 7.1.2Line Terminators
    2. 7.2Common Definitions
      1. 7.2.1Identifier
      2. 7.2.2Profile Identifier
      3. 7.2.3Full Profile Identifier
      4. 7.2.4Map Profile Identifier
      5. 7.2.5Provider Identifier
      6. 7.2.6Service Identifier
      7. 7.2.7URL Value
      8. 7.2.8Security Scheme Identifier
      9. 7.2.9String Value
      10. 7.2.10Integer Value
  8. §Index