Known Types

Well-known types for Rust.

[Features] | [Prerequisites] | [Installation] | [Examples] | [Reference] | [Development]

✨ Features

• Zero default dependencies, only optional integrations.
• Supports opting out of any feature using comprehensive feature flags.
• Adheres to the Rust API Guidelines in its naming conventions.
• Cuts red tape: 100% free and unencumbered public domain software.

🛠️ Prerequisites

• Rust 1.85+ (2024 edition)

⬇️ Installation

Installation via Cargo

cargo add known-types

Installation via Cargo (all crates)

cargo add known-types
cargo add known-types-anthropic
cargo add known-types-github
cargo add known-types-google
cargo add known-types-graphql
cargo add known-types-gravatar
cargo add known-types-ietf
cargo add known-types-instagram
cargo add known-types-linkedin
cargo add known-types-luma
cargo add known-types-nostr
cargo add known-types-openai
cargo add known-types-pypi
cargo add known-types-rubygems
cargo add known-types-w3c
cargo add known-types-x

Installation in Cargo.toml

Enable all default features:

[dependencies]
known-types = "0"

Installation in Cargo.toml (with all features enabled, in all crates)

[dependencies]
known-types = "0"
known-types-anthropic = "0"
known-types-github = "0"
known-types-google = "0"
known-types-graphql = "0"
known-types-gravatar = "0"
known-types-ietf = "0"
known-types-instagram = "0"
known-types-linkedin = "0"
known-types-luma = "0"
known-types-nostr = "0"
known-types-openai = "0"
known-types-pypi = "0"
known-types-rubygems = "0"
known-types-w3c = "0"
known-types-x = "0"

Enable only specific features:

[dependencies]
known-types = { version = "0", default-features = false, features = ["serde"] }

Installation in Cargo.toml (with only specific features enabled, in all crates)

[dependencies]
known-types = { version = "0", default-features = false, features = ["serde"] }
known-types-anthropic = { version = "0", default-features = false, features = ["serde"] }
known-types-github = { version = "0", default-features = false, features = ["serde"] }
known-types-google = { version = "0", default-features = false, features = ["serde"] }
known-types-graphql = { version = "0", default-features = false, features = ["serde"] }
known-types-gravatar = { version = "0", default-features = false, features = ["serde"] }
known-types-ietf = { version = "0", default-features = false, features = ["serde"] }
known-types-instagram = { version = "0", default-features = false, features = ["serde"] }
known-types-linkedin = { version = "0", default-features = false, features = ["serde"] }
known-types-luma = { version = "0", default-features = false, features = ["serde"] }
known-types-nostr = { version = "0", default-features = false, features = ["serde"] }
known-types-openai = { version = "0", default-features = false, features = ["serde"] }
known-types-pypi = { version = "0", default-features = false, features = ["serde"] }
known-types-rubygems = { version = "0", default-features = false, features = ["serde"] }
known-types-w3c = { version = "0", default-features = false, features = ["serde"] }
known-types-x = { version = "0", default-features = false, features = ["serde"] }

👉 Examples

Importing the Library

use known_types;

Importing the library (all crates)

use known_types;
use known_types_anthropic;
use known_types_github;
use known_types_google;
use known_types_graphql;
use known_types_gravatar;
use known_types_ietf;
use known_types_instagram;
use known_types_linkedin;
use known_types_luma;
use known_types_nostr;
use known_types_openai;
use known_types_pypi;
use known_types_rubygems;
use known_types_w3c;
use known_types_x;

Using handles with async-graphql

All handle crates support async-graphql 7.2 through the optional async-graphql feature. It enables std (and alloc) and implements ScalarType, InputType, OutputType, and connection::CursorType. It also works with default-features = false and requires no serde feature on the handle crate.

For example, to use XHandle as a query argument and return value:

[dependencies]
known-types-x = { version = "0.1", default-features = false, features = ["async-graphql"] }
async-graphql = { version = "7.2", default-features = false }

use async_graphql::Object;
use known_types_x::XHandle;

struct Query;

#[Object]
impl Query {
    async fn handle(&self, input: XHandle) -> XHandle {
        input
    }
}

The resulting field is handle(input: XHandle!): XHandle!. Queries can pass string literals or variables declared as XHandle, for example:

query($handle: XHandle!) {
  handle(input: $handle)
}

With variables {"handle": "Some_User"}, this returns {"data": {"handle": "Some_User"}}. Handles also work in InputObject and SimpleObject fields, Option<Handle>, and Vec<Handle>.

Each handle has its own scalar name matching its Rust type: XHandle, FacebookHandle, GithubHandle, GravatarHandle, InstagramHandle, IntrocoHandle, LinkedinHandle, LocalaiHandle, LumaHandle, TelegramHandle, and WhatsappHandle. Scalars accept only GraphQL strings and serialize to strings. LinkedinHandle input uses its existing FromStr validation and normalization (trimming whitespace and percent-decoding UTF-8); invalid input returns a GraphQL input error. The other handles preserve their input verbatim.

Handles as connection cursors

All handles implement connection::CursorType under the same feature, so they can be used directly in Connection<Handle, Node> and Edge<Handle, Node>. Like async-graphql's String cursors, they encode the stored string verbatim and decode infallibly. This preserves XHandle's existing cursor format and ensures that already-normalized LinkedIn handles round-trip without double-decoding percent escapes or trimming meaningful whitespace.

Handle cursors are appropriate when the handle is the unique ordering key for the connection. The application supplies deterministic pagination ordering and decides how handle renames affect that ordering; CursorType supplies the reversible encoding.

Using handles with SQLx

All handle crates support SQLx 0.9 through optional features:

For example, to use XHandle with PostgreSQL:

[dependencies]
known-types-x = { version = "0.1", features = ["sqlx-postgres"] }
sqlx = { version = "0.9", default-features = false, features = ["postgres", "runtime-tokio"] }

use known_types_x::XHandle;

async fn round_trip(pool: &sqlx::PgPool, handle: &XHandle) -> Result<XHandle, sqlx::Error> {
    sqlx::query_scalar("SELECT $1::text")
        .bind(handle)
        .fetch_one(pool)
        .await
}

Handles can be bound by value or reference, decoded from string columns, and wrapped in Option for nullable columns. PostgreSQL also supports Vec<Handle> for text arrays. Decoding preserves the stored string without parsing or normalizing it again.

The same features are available for FacebookHandle, GithubHandle, GravatarHandle, InstagramHandle, IntrocoHandle, LinkedinHandle, LocalaiHandle, LumaHandle, TelegramHandle, and WhatsappHandle in their respective crates. If the application already enables its database driver on sqlx, enabling just sqlx on a handle crate is sufficient. SQLx support is disabled by default and also works with default-features = false.

When using SQLx's compile-time query macros, use an explicit column type override such as SELECT handle AS "handle: XHandle" with query!, or SELECT handle AS "handle: _" with query_as! and a struct field of type XHandle.

📚 Reference

docs.rs/known-types

Crates

Crate	Version	Docs	Summary
known-types			Well-known types.
known-types-anthropic			Well-known types for Anthropic APIs.
known-types-github			Well-known types for GitHub APIs.
known-types-google			Well-known types for Google APIs.
known-types-graphql			Well-known types for GraphQL specifications.
known-types-gravatar			Well-known types for Gravatar APIs.
known-types-ietf			Well-known types for IETF specifications.
known-types-instagram			Well-known types for Instagram APIs.
known-types-linkedin			Well-known types for LinkedIn APIs.
known-types-luma			Well-known types for Luma APIs.
known-types-nostr			Well-known types for the Nostr protocol.
known-types-openai			Well-known types for OpenAI APIs.
known-types-pypi			Well-known types for Python Package Index (PyPI) APIs.
known-types-rubygems			Well-known types for RubyGems.org APIs.
known-types-w3c			Well-known types for W3C specifications.
known-types-x			Well-known types for X (formerly Twitter) APIs.

Integrations

Crate (Feature)	Version	Usage	Summary
async-graphql  ("async-graphql")	7.2		Implements ScalarType, InputType, OutputType, and connection::CursorType for handles
bincode  ("bincode")	2		Derives bincode::{Encode, Decode}
borsh  ("borsh")	1.5		Derives borsh::{BorshSerialize, BorshDeserialize}
musli  ("musli")	0.0.131		Derives musli::{Encode, Decode}
rasn  ("rasn")	0.26		Derives rasn::AsnType with rasn(automatic_tags)
serde  ("serde")	1		Derives serde::{Serialize, Deserialize}
SQLx  ("sqlx")	0.9		Implements sqlx::{Type, Encode, Decode} for handles

See Also

Package	Crate	Docs
known-errors
known-languages
known-paths
known-schemes
known-types

👨‍💻 Development

git clone https://github.com/it-is-known/known-types.git