Skip to content

Overview

Status: Specification 1.0.0-rc.1.

Independent generators, in any language and on any framework, produce code from the same contract that works together without further agreement.

Everything in this specification serves that goal. A JVM backend generated by one tool on one framework and a Flutter frontend generated by another tool on another framework must agree on identity, presence, constraints, queries, pagination, errors and ownership, because the contract states them unambiguously.

OpenAPI does this for the HTTP API. Rialto does it for the whole application: domain, REST, mappings, storage and views.

shipment.rialto.yaml
(+ openapi.json, schema.sql)
┌──────────────┼──────────────┐
JVM generator Flutter generator other generator
│ │ │
mappers, codecs, models, clients, …
storage adapters forms, views
│ │
+ authored code + authored code
+ framework + framework

Anything two generated components depend on to work together is stated in the contract: names, types, presence, constraints, encodings, pagination, error categories, ownership. A generator never fills such a gap with its own convention.

Why: conventions differ per framework. If one is implicit, a backend and a frontend from different tools silently disagree.

Where several good conventions exist, Rialto does not pick one. It defines a closed set of fully specified strategies, and the contract selects one explicitly:

Concern Strategies (examples)
pagination cursor, offset
filter encoding an RSQL subset, others as specified
partial update field presence (absent, null, value)
error format problem details with declared categories and codes

A generator supports a subset and rejects a contract that selects a strategy it does not support. A framework may be opinionated: support only cursor pagination, for instance, and write that choice into the contracts its tooling produces. The specification stays open; every contract stays unambiguous.

Why: an opinionated specification excludes valid architectures; an implicit choice breaks interoperability. Explicit, closed choices avoid both.

Generated code handles technical concerns: mapping, encoding, storage access, wiring. Business decisions (invariants, permissions, workflows) are authored code, reached through declared seams that can be extended or replaced. Regeneration never touches authored code.

Client (generated) ──HTTP──▶ Server adapter (generated: auth, preconditions, codecs)
│
Mapper (generated)
│
Authored handler / policy seam
│
Storage adapter & outbox (generated)

Generation happens at build time. Generated code needs no generator at runtime and only declared, minimal dependencies. The specification requires no framework, base class or runtime library.

How a contract comes into being is free:

Mode Flow
contract-first write the contract; generate domain types, REST, storage and views from it
code-first annotate source code; an exporter produces the contract; other generators use that contract
mixed for example: domain annotated in Kotlin and exported, views added to the contract by hand, Dart code generated from the result

Whatever the mode, the contract is the single exchange point between tools. An exporter must produce a complete, valid contract, and code generated from a contract must export back to an equivalent contract (C8.1, C8.2).

Component Role
Specification (this repository) contract format, terminology, profiles, generator obligations
Tooling tooling per language: load and validate contracts, export them from annotated code, a typed contract model, a plugin API for generators, compatibility checks
Generators produce code for one stack; a reference generator comes first, anyone can add their own

This mirrors the model of OpenAPI and openapi-generator: one contract, several generators, each producing code in its own style. It is an analogy, not a dependency: a generator need not use openapi-generator. The contract is the exchange format between all components; each may use its own internal representation.

Part Defines
Contract the document format, type system and references; formalized in a JSON Schema
Core terminology and the rules every generator follows
Profiles the meaning of each contract section and what generated code for that layer must do: domain, REST, mapping, persistence, query, errors, lifecycle, versioning, events, auth, presentation
Generators what a generator for one stack may choose, and what it must document

Profiles are independent: a mapper generator implements only the mapping profile and ignores the other sections. The Shipment example shows one contract across all profiles.

The profiles, Generators and the Shipment example are not published yet: the specification is built towards 1.0.0 in slices, and each slice adds its profile (see the README).

Concern Contract Generator Runtime libraries Application
meaning of types, operations, mappings, storage and views defines — — authors the contract
infrastructure code (mappers, codecs, adapters, views) — generates — —
execution (HTTP, SQL, UI widgets, transactions) — — provides chooses
business decisions (permissions, invariants, workflows) references them invokes them through seams — implements them
Concern Authoritative source
REST wire format the OpenAPI documents the contract references
event channels and messages the AsyncAPI documents the contract references
database shape the SQL schema the contract references
meaning, correspondence, ownership, strategies the Rialto contract
invariants and business decisions authored application code
theme values and copy the application’s design and localization sources

A generator reports contradictions between these sources and never lets one silently redefine another (C5.3, C5.4). A contract can reference several versions of an API (for example api-v1 and api-v2), each mapped to the same domain, so layers evolve independently.

Why: OpenAPI and SQL already have mature tooling; Rialto adds what they cannot express: how their elements correspond to each other and to the domain.

Version 1 covers one contract that generates, through Rialto tooling and the reference generator, a complete application: REST backend with storage, search and lists, events, forms and errors in a frontend. The specification must stay implementable by other generators. The tooling and reference generator implement every profile except the presentation profile on the JVM; the presentation profile (views and forms) is implemented in Flutter.

Area Status
contract format, core, domain, mapping, REST, persistence, query, errors, lifecycle, versioning, events, auth specified; implemented by the reference generator
presentation (views, forms, live views) specified; the reference implementation in Flutter follows
Rialto tooling: contract model, validation, export, compatibility, plugin API available for the JVM and Dart
reference generator for the JVM (server) available, see tooling
reference generator for Flutter (client, views) planned
  • Frameworks, class libraries, base classes or runtime libraries for any platform.
  • Business logic, authorization rules or workflows.
  • A database engine, ORM, DI container or UI widget set.
  • Tokens and localization formats: views reference them; their format belongs to the application’s design tooling.
  • Build tool integration, package names and directory layout: these belong to the generator configuration.

Not in version 1, and open for a later version:

  • Push notifications to apps that are not running (Web Push, RFC 8030, and platform push services).
  • Other API styles than REST over HTTP, such as GraphQL and gRPC.
  • Storage other than relational databases, such as document stores.
  • Event data in other formats than JSON, such as Avro or Protocol Buffers.
  • Generating OpenAPI, AsyncAPI and SQL documents from the contract.