Kival Types
kival-types provides the canonical Rust vocabulary shared by Kival's kernel and public Rust SDK.
It defines stable concepts whose meaning is common across Kival's internal model and HTTP interface, including API-key scopes, authorization roles, lifecycle states, search modes, graph traversal, and event ordering. Transport-specific request and response models remain in kival-sdk.
Most applications interacting with Kival over HTTP should use kival-sdk, which re-exports the relevant types from this crate. Depend on kival-types directly when you need Kival's shared vocabulary without the SDK's complete wire model or HTTP client.
Features
kival-types has no default features.
The core crate provides Kival's types without requiring Serde or Schemars:
[]
= "0.1"
Enable the wire feature to add serde::Serialize, serde::Deserialize, and schemars::JsonSchema implementations:
[]
= { = "0.1", = ["wire"] }
This is useful for servers, schema tooling, protocol implementations, and other crates that need Kival-compatible serialization without depending on the full SDK.
Vocabulary
The crate includes shared types for:
- API-key capabilities through
ApiKeyScope; - object and membership authorization through
ObjectRole,MembershipRole, andGrantPrincipal; - resource lifecycle and collection filtering through
ArchiveStatus,ArchiveListStatus,UserStatus, andUserListStatus; - object collection ordering through
ObjectListOrder; - search behavior through
SearchCategory,SearchMode, andSearchMatchKind; - graph traversal through
ObjectGraphDirection; - commentary lifecycle through
CommentStatus; - event ordering through
EventOrder.
Stored and serialized values are stable parts of Kival's contract. Types that expose as_str return their canonical representation, while parsing implementations accept those same representations where applicable.
For example:
use ;
assert_eq!;
assert_eq!;
let role: ObjectRole = "admin".parse.expect;
assert_eq!;
API-key scopes
ApiKeyScope defines Kival's API-key capability vocabulary from a single canonical source.
Write scopes satisfy their corresponding read capability:
use ApiKeyScope;
assert!;
assert!;
Unrelated capabilities do not imply one another. Administrative authority, realtime access, event access, and resource capabilities remain independently scoped.
ApiKeyScope::ALL exposes every supported scope in stable declaration order.
Using kival-sdk
The public Rust SDK re-exports the Kival types that form part of its HTTP interface, so SDK consumers generally do not need a separate kival-types dependency:
use ;
Use kival-types directly when sharing these concepts with code that should not depend on Kival's transport-specific request and response types or client implementation.
Scope
kival-types intentionally contains only concepts whose semantics are shared across Kival boundaries.
HTTP request and response structures, pagination envelopes, API errors, realtime messages, and other transport-specific models belong to kival-sdk. Kernel-specific persistence and execution types remain internal to Kival.
Keeping this boundary small gives Kival one canonical definition for shared vocabulary without coupling the kernel to the public SDK's transport model.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.