RuslRusl
Concepts

What Rusl is, what it is not, and how to use it.

Rusl is the collaborative contract layer around JSON Schema. It helps humans and agents resolve the same shape, meaning, package graph, feedback, and trust signals before code changes.

Start with toolingRead the thesis
What Rusl is

A registry, package workflow, and semantic graph for JSON Schema-based contracts.

A registry for JSON Schema-based contracts.

A package workflow for installing and resolving schema dependencies.

A semantic graph of annotations, usage reports, links, provenance, and trust signals.

A shared surface for humans, tools, and agents to reuse the same contract.

What Rusl is not

Rusl supplies shared contracts and context. Your stack still chooses the runtime machinery.

Not a new schema language.

Not your runtime validator.

Not a serialization format.

Not primarily a code generator.

Where do I use this?

Use Rusl wherever a data boundary can drift.

Backend validation near persistence
Validate shape where incorrect data becomes durable without losing the meaning the rest of the stack expects.
Domain object inputs and outputs
Keep DTOs and service boundaries aligned with the same published meaning.
OpenAPI request and response contracts
Publish API contracts from shared schemas instead of creating one-off interpretations.
MCP tool params and results
Expose shape plus interpretation so agents know how a tool contract should be used.
Frontend forms and client validation
Build forms and client validators from the same contract backend systems enforce.
UI rendering metadata
Resolve annotations that describe labels, widgets, risk, display rules, and examples.
Consumption modes

Install contracts into a project or resolve them live.

npm-style
Build-time install
Use the project manifest and CLI workflows to install pinned schemas into a project for generation, validation, review, and tests.
live
Runtime resolution
Fetch schema contents and semantic context directly when an app or agent needs the latest resolvable contract.
rusl.bundle.toml
[rusl.resources]
"rusl/bundles/feedback-schemas" = "~>0.1"
"rusl/schemas/common" = "~>0.1"
CLI workflow

It works like the package managers you already know.

Think Cargo, npm, Bundler, or Mix deps, but for shared data contracts. The manifest names what the project depends on. The version constraints define what is acceptable. The install step makes the resolved contracts available locally.

Declare dependencies
Create a project manifest with community bundles or direct schema references, then constrain versions the same way you would with package dependencies.
Install the graph
Run the install command to resolve compatible versions, fetch the schemas, and store them in the project for local tooling.
Let tools consume them
Once installed, schemas are locked and loaded for generation, validation, review, tests, forms, and agent workflows.
package-manager muscle memory
rusl add rusl/bundles/feedback-schemas
rusl install
rusl list
rusl --help
Core nouns

The product vocabulary is small on purpose.

Schema
The JSON Schema-based contract that defines valid data shape.
Version
An immutable release target consumers can pin, cache, review, and depend on.
Bundle
A versioned package of related schema dependencies that resolve together.
Proposal
The review workflow for changing a shared contract before it becomes a new version.
Annotation
Typed semantic data attached to a schema, version, bundle, proposal, or other Rusl subject.
Annotation type
The schema for a kind of annotation, so semantic content has its own dependable shape.
Accounts and visibility
Namespaces and public or private access rules that control who can resolve a resource.
Discovery and trust
The signals consumers use to find contracts and decide whether to depend on them.
CLI and MCP access
Tooling surfaces that let projects and agents resolve contracts instead of copying examples.
Standard feedback schemas

First-class annotation types turn agent feedback into reusable contract context.

context-loading-hint

Guidance for what context an agent should load before using a contract.

usage-report

A report that a contract was used in a project, tool call, generator, validator, or workflow.

domain-interpretation

Typed explanation of what a field or contract means in a specific domain.

semantic-link

A typed relationship between contracts, fields, annotations, docs, or external sources.

trust-signal

Evidence that helps a consumer decide whether a contract or annotation is dependable.

context-request

A structured request for missing meaning when an agent or human cannot safely proceed.

source-attestation

A claim that connects a contract or annotation back to its source of authority.

migration-guide

Version-to-version guidance for compatibility, breaking changes, and upgrade work.

domain-interpretation annotation
{
  "annotation_type": "rusl/annotation-types/domain-interpretation",
  "subject": "rusl/schemas/customer@1.2.0#/properties/email",
  "content": {
    "meaning": "Primary contact address for account communication.",
    "visibility": "user-visible",
    "risk": "Do not reuse as login identity without local auth policy."
  }
}
Agent behavior model

Agents should resolve the shared contract before producing local shape.

This is the behavioral contract Rusl is designed to support.

  1. 01Query before guessing.
  2. 02Reuse before inventing.
  3. 03File context requests when blocked by missing meaning.
  4. 04Contribute domain interpretations when real usage teaches missing context.
Open agent guideInstall tooling