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.