Component Specification

The VALAWAI toolbox consists of components that can be combined to create value-aware applications. These components adhere to specific conventions and file structures, as described below. The architectural teams involved in the VALAWAI project have established these guidelines to ensure consistency, clarity, and functionality in component development and integration.

Name Format

Component names follow the format C[0|1|2]_component_name, where [0|1|2] represents the component type (C0, C1, or C2), and component_name is a descriptive name in lowercase Python case. For example, a C0 component named "voice to text" would be named C0_voice_to_text.

Version Schema

All components follow Semantic Versioning, structured as major.minor.bug. The version number reflects the component's development status. For example, the initial version is 1.0.0. After seven minor changes and two bug fixes, the version becomes 1.7.2.

Backward compatibility is guaranteed only for minor versions within the same major version. While backward compatibility across major versions is encouraged, it's not mandatory.

License

Components in the RGNW toolbox are primarily distributed under the GPLv3 license. While this license is recommended, other licenses are permitted. The specific license used must be clearly documented.

Repository

The source code for all VALAWAI components is publicly available on GitHub under the VALAWAI organization. This promotes transparency and collaboration.

Deployment

Components are deployed using Docker and Docker Compose. This ensures structured and efficient deployment, clearly defining the component and its integration with platforms like the Master Of VALAWAI (MOV), as well as any necessary databases or message queues (e.g., RabbitMQ).

Required Files

Each component must include the following files:

• README.md: A comprehensive overview of the component, including a brief description, key features and functionalities, build instructions, deployment procedures, and any dependencies.

• LICENSE: The component's license information.

• CHANGELOG.md: A record of significant changes across all public versions, detailing new features, bug fixes, enhancements, and any breaking changes, along with upgrade instructions.

• asyncapi.yaml: A description of the component's services in standard AsyncAPI format, detailing endpoints, message structures, and parameters.

• docker-compose.yml: A Docker Compose file for deploying the component, including necessary configurations, environment variables, and service dependencies.

Interaction Specification

The component's services are described in the asyncapi.yaml file, using the AsyncAPI specification version 2.6.0. The key sections are:

• info: General component information (title, version, description, contact, license).
• channels: Description of sent and received messages.
• components: Message and schema definitions.

The info section defines title (e.g., "VALAWAI C0 Voice to text"), version, description, contact (partner name and URL), and license.

The channels section describes each service (one channel per service) using the template valawai/c[0|1|2]/component_name/[control/data]/operation_name. This template uses lowercase letters, Python case, and satisfies the RFC 6570 URI template. For example, a C0 "voice to text" component's service for processing audio might be named valawai/C0/voice_to_text/data/audio_to_process. Channels are defined as publish (sends messages), subscribe (receives messages), nor both. A summary field provides a one-sentence description when both are used. Each message is referenced.

The components section contains messages (with contentType: application/json and a schema reference) and schemas (describing message content). Message and schema names use lowercase Python case. Schema properties use lowercase Python case and include type and description, with optional examples.

Below is an example of an asyncapi.yaml description for a C0 component that extracts text from an audio file:

asyncapi: '2.6.0'
info:
  title: VALAWAI C0 Voice to text
  version: '0.1.0'
  description: |
    This component converts an audio file into text.
  contact:
    name: IIIA-CSIC
    url: https://www.iiia.csic.es
  license:
    name: GPL v3
    url: https://opensource.org/license/gpl-3-0

channels:
  valawai/c0/voice_to_text/data/audio_to_process:
    subscribe:
      summary: Provide the audio text to extract the text.
      message:
        $ref: '#/components/messages/audio_content'

  valawai/c0/voice_to_text/data/text_extracted:
    publish:
      summary: Notify about the extracted text from a received audio.
      message:
        $ref: '#/components/messages/text_content'

  valawai/c0/voice_to_text/control/set_paremeters:
    subscribe:
      summary: Modify the parameters of the component.
      message:
        $ref: '#/components/messages/parameters_content'

  valawai/c0/voice_to_text/control/registered:
    description: The message to notify when the component has been registered.
    subscribe:
      message:
        $ref: '#/components/messages/registered_component'

components:
  messages:
    audio_content:
      contentType: application/json
      payload:
        $ref: "#/components/schemas/audio_payload"

    text_content:
      contentType: application/json
      payload:
        $ref: "#/components/schemas/text_payload"

    parameters_content:
      contentType: application/json
      payload:
        $ref: "#/components/schemas/parameters_payload"

    registered_component:
      contentType: application/json
      payload:
        $ref: '#/components/schemas/component_payload'

  schemas:
    audio_payload:
      type: object
      properties:
        sample_ratio:
          type: string
          description: The frequency that this audio is sampled on kHz.
          examples:
            - 96
        encoded:
          type: string
          description: Type of the audio encoding.
          examples:
            - 'audio/ogg'
        sample:
          type: string
          description: The binary sample of the audio in Base64.
    text_payload:
      type: object
      properties:
        text:
          type: string
          description: The speech is found on the audio.
        language:
          type: string
          description: The detected language of the text.
          examples:
            - 'English'
        accuracy:
          type: number
          min: 0
          max: 100
          description: The accuracy that the text i what can be listening on the audio.
          examples:
            - 98.7
    parameters_payload:
      type: object
      properties:
        default_language:
          type: string
          description: The language to use if it is not possible to infer the audio language.
          examples:
            - 'English'

    component_payload:
      type: object
      properties:
        id:
          description: The identifier of the component.
          type: string
          pattern: '[0-9a-fA-F]{24}'
          examples: 
            - '65c1f59ea4cb169f42f5edc4'
        name:
          description: The name of the component.
          type: string
          examples: 
            - 'c0_voice_to_text'
        description:
          description: The description of the component.
          type: string
          examples: 
            - 'Generate text from the ambient audio'
        version:
          description: The component version.
          type: string
          pattern: '\d+\.\d+\.\d+'
          examples: 
            - '1.0.5'
        api_version:
          description: The version of the component API.
          type: string
          pattern: '\d+\.\d+\.\d+'
          examples: 
            - '2.3.0'
        type:
          description: The type level of the component in the VALAWAI.
          oneOf:
            - $ref: '#/components/schemas/component_type'
        since:
          description: The epoch time, in seconds, since the component is available in VALAWAI.
          type: integer
          minimum: 0
          examples: 
            - '1709902001'
        channels:
          description: The channels that the component have.
          type: array
          items:
            - $ref: '#/components/schemas/channel_schema'

    component_type:
      type: string
      enum:
        - 'C0'
        - 'C1'
        - 'C2'

    channel_schema:
      type: object
      description: A schema that define the messages that a channel can receive or send.
      properties:
        id:
          description: The identifier of the channel.
          type: string
          examples: 
            - 'valawai/c0_voice_to_text/audio'
        description:
          description: The description of the channel.
          type: string
          examples: 
            - 'Provide the audio to convert to text'
        subscribe:
          description: The type of payload that the channel can receive.
          oneOf:
            - $ref: '#/components/schemas/payload_schema'
        publish:
          description: The type of payload that the channel can send.
          oneOf:
            - $ref: '#/components/schemas/payload_schema'

    payload_schema:
      type: object
      discriminator: type
      properties:
        type:
          type: string
          enum:
            - BASIC
            - ENUM
            - OBJECT
            - ARRAY
            - CONST
            - REF
            - ONE_OF
            - ANY_OF
            - ALL_OF
      required:
        - type

    basic_payload_schema:
      description: The basic payload schema.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'BASIC'
            format:
              type: string
              description: The format of the basic type.
              enum:
                - 'INTEGER'
                - 'NUMBER'
                - 'BOOLEAN'
                - 'STRING'

    enum_payload_schema:
      description: A payload that is defined of one value of a set.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'ENUM'
            values:
              type: array
              description: The possible enum values.
              items:
                - type: string

    object_payload_schema:
      description: A definition of a schema that describe an object.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'OBJECT'
            id:
              type: integer
              description: The identifier used whne this schme is refer by other components.
            properties:
              description: The properties that define the object.
              additionalProperties:
                $ref: '#/components/schemas/payload_schema'
            
    array_payload_schema:
      description: A payload that is represented by an array of values.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'ARRAY'
            items:
              description: The type for the elements on the array.
              type: array
              items:
                - $ref: '#/components/schemas/payload_schema'

    constant_payload_schema:
      description: A payload that is a consatnt value.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'CONST'
            value:
              type: string
              description: The constant of the schema.

    reference_payload_schema:
      description: A payload that is a reference to another schema.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'REF'
            value:
              type: integer
              description: The identifier of the schema that this a reference.

    one_of_payload_schema:
      description: A payload that is one of the possible schemas.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'ONE_OF'
            items:
              description: The possible schemas.
              type: array
              items:
                - $ref: '#/components/schemas/payload_schema'

    any_of_payload_schema:
      description: A payload that is any of the possible schemas.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'ANY_OF'
            items:
              description: The possible schemas.
              type: array
              items:
                - $ref: '#/components/schemas/payload_schema'

    all_of_payload_schema:
      description: A payload that is a set of schemas.
      allOf:
        - $ref: '#/components/schemas/payload_schema'
        - type: object
          properties:
            type:
              const: 'ALL_OF'
            items:
              description: The schemas that has to match.
              type: array
              items:
                - $ref: '#/components/schemas/payload_schema'

Special Channels for MOV Integration

When using the Master of VALAWAI (MOV), specific channel patterns enable integration:

1. Registration Channel (valawai/c[0|1|2]/component_name/control/registered): If this channel is defined, the MOV publishes a message to it upon component registration. This message contains component information (id, name, description, version, api_version, type, since, channels).

2. C2 Notification Channel (valawai/c2/\w+/control/\w+): This channel is exclusively for C2 components. It notifies the C2 component about messages exchanged between other components via a topology connection. The channel name matches the pattern valawai/c2/component_name/control/service_name. The subscribe message payload schema includes:

   • connection_id: ID of the topology connection.
   • source: Information (id, name, type) of the source component.
   • target: Information (id, name, type) of the target component.
   • message_payload: The message payload that was exchanged.
   • timestamp: Epoch time of the message send.

   The MOV uses this channel to notify C2 components about messages sent through active topology connections that match the message_payload type. Specifically, when a connection is registered, the MOV checks for registered C2 components with a matching C2 Notification Channel and message_payload type. Conversely, when a C2 component with this channel type is registered, the MOV checks for existing connections with a matching message_payload and adds the C2 component to those connections for notifications.