Skip to main content
Version: Unreleased 🚧

Terminology

This document lists and explains all terms used through the Capact documentation.

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

Common terms

Capability

Characteristic of an application, described with an Interface or Implementation. A capability may be a prerequisite (dependency) for other Implementations.

Action

Task that the Engine schedules, and the Runner executes. Action is usually in a form of an arbitrary workflow.

Runner

Action, which handles execution of other Action. Runner is usually defined in form of Interface and Implementation.

There is also a built-in Runner, which is built-in into platform-specific Engine implementation. It is defined with only abstract Interface and doesn't have Implementation manifest.

To learn more about runners, see the dedicated runner.md document.

Components

There are the following components in the system:

Entities

There are the following entities in the system:

RepoMetadata

RepoMetadata stores read-only information about the Hub, such as Hub version, supported OCF specification version, etc. This entity should be placed in the core directory in your Hub content. In the future, it will be embedded into the Hub server.

The RepoMetadata format is defined in repo-metadata.json.

note

Currently, the spec.implementation and spec.ocfVersion.supported properties are not supported by the Hub server.

Attribute

Attribute provides an option to categorize Implementations, Types and TypeInstances. For example, you can use cap.core.attribute.workload.stateful Attribute to find and filter Stateful Implementations.

The Attribute specification is defined in attribute.json.

Type

Type represents an object, such as database, application, but also a simple primitive data, like an IP address. The Type needs to be described using JSON Schema specification.

Type is used in Interface and Implementation as a description and validation of possible input and output parameters. The object, which stores a JSON value matching JSON schema from Type, is called TypeInstance.

The core Types are placed in the core directory. In the future, core Types will be embedded into the Hub server.

To learn more, see the Type features document.

The Type specification is defined in type.json.

note

Currently, Type validation based on JSON Schema is not supported.

TypeInstance

Capact is strongly typed, and all objects must be described with JSON Schema. An actual object of a Type is called a TypeInstance. Data stored in an object MUST be valid against JSON Schema from referenced Type.

note

In the future, details about health and metrics of a given TypeInstance will be attached to it. Currently, this functionality is not implemented. To learn more, see the "Extend TypeInstance with instrumentation and metrics" issue.

Interface

Interface defines an action signature. It describes the action name, input, and output parameters. It is a similar concept that the one used in programming languages.

The Interface specification is defined in interface.json.

InterfaceGroup

InterfaceGroup logically groups various Interfaces. This allows end-users to find all Interfaces, which for example operate on PostgreSQL instances. InterfaceGroup is required even if you have only one Interface.

The InterfaceGroup specification is defined in interface-group.json.

Implementation

Implementation holds the definition of an Action and its prerequisites (dependencies). It allows you to define different ways on how a given action should be executed. For example, for postgres.install Interface, have aws.postgresql.install and gcp.postgresql.install Implementations. Implementation must implement at least one Interface.

The Implementation specification is defined in implementation.json.

Vendor

Vendor defines details of an external Hub server. This will be part of the Hub federation feature.

The Vendor specification is defined in vendor.json.

note

Currently, it is not supported by the Hub server.