Questions

Questions teams ask before depending on shared schemas.

Shape is versioned. Meaning is typed. Reuse happens through explicit references.

These answers cover the decision points: why the registry exists, what counts as a durable contract, how typed annotations work, and how agents use the same schema references as humans and tools.

15 answers
Short, exact answers for product nouns that should stay stable.
Primary contractschema
Release targetversion
Meaning layerannotation
Agent pathCLI and MCP
01

Why Rusl exists

Rusl gives a data shape one place to live — versioned, referenceable, and reused — instead of redrawn in every project.

3 questions

Why does Rusl exist?

So a data shape can be defined once, shared, and versioned — instead of every project redrawing Customer, Address, or Order and paying to reconcile the copies. The argument for that is the manifesto's; Rusl is where it becomes real.

Read the thesis

What is Rusl?

Rusl is where your data schemas live — versioned, shared, and reusable — together with the typed context that explains them. Humans, tools, and agents resolve the same references.

Read the concepts

Why is this not just better documentation?

Documentation helps people understand intent, but prose is a weak dependency target. Rusl makes the contract itself explicit: a schema URL can be referenced, versioned, downloaded, installed, annotated, and validated by tools.

Version concept
02

Contracts and releases

Schemas become useful infrastructure when consumers can resolve specific versions and package related contracts together.

4 questions

What is a schema?

A schema is a reusable contract for the shape and validation rules of data. Rusl currently builds on JSON Schema because it is full-featured, battle-tested, and supported across languages. Rusl is not trying to invent a new schema language; it gives schemas a registry, versions, immutable downloads, bundles, annotations, and discovery so they can be reused as shared infrastructure.

Schema concept

How do versions work?

A version is an immutable published point in a schema or bundle history. Once a schema version is published, it is available as a cached immutable download, so consumers should depend on explicit versions instead of a mutable idea of latest.

Version concept

Can I download a published schema version?

Yes. Published schema versions are durable artifacts. Tools, services, build systems, command-line tools, and agents can cache a versioned download because the content for that version will not be rewritten.

Version downloads

What is a bundle?

A bundle is a versioned package of schemas. It declares a coherent dependency graph so consumers resolve the same set of contracts instead of assembling a schema set by memory or copy-paste.

Bundle concept
03

Annotations and trust

Schemas define data shape. Annotations let people, tools, and agents attach typed meaning around that shape.

6 questions

What is an annotation?

An annotation is typed content attached to a subject and validated against its annotation type's schema. People, tools, and agents use them to attach meaning — interpretation, retention, trust, usage — without owning or forking the schema.

Annotation concept

Why are annotations so important?

A shared shape gets more useful every time someone attaches reliable meaning around it. Annotations are typed — each is validated against its type's schema — so consumers and agents can depend on the shape of that meaning instead of scraping comments.

Annotation concept

What is an annotation type?

An annotation type is a name paired with a schema — not itself a schema. The schema validates the content of every annotation of that type, so consumers and agents can rely on its shape.

Annotation type concept

Why not put every meaning directly inside the schema?

Schemas should define data shape. Annotations let UI, governance, audit, storage, documentation, and internal policy meanings evolve around that shape without bloating or forking the schema.

Annotation concept

Can multiple tools annotate the same subject?

Yes. Rusl allows multiple annotations of the same type on one subject. Precedence is a consumer or annotation-type policy, not a global registry rule.

Annotation rules

How do people decide what to trust?

Trust comes from explicit choices: publisher identity, versions, visibility, reuse signals, watchers, favorites, annotation counts, bundle inclusion, and the annotation types a consumer understands.

Discovery and trust
04

Tooling and agents

The CLI and the embedded MCP server give code and agents a concrete way to resolve and use contracts.

2 questions

What is the Rusl CLI?

The Rusl CLI is the schema package manager. A local bundle manifest controls what gets fetched, resolved, and installed into the application directory. From there, schemas can be used by the app, committed according to the project workflow, or fed into generators.

CLI and agents

How will agents use Rusl?

Through the CLI and its embedded MCP server (rusl mcp): agents search, fetch schemas and examples, and write context back — using the same references humans and tools do. The Claude Code Agent Kit wires this up in one step.

CLI and agents
Still deciding

The shortest version: depend on versioned schemas when shape needs to be stable, and use annotations when meaning needs to evolve around that shape.