Changelog
All notable changes for readers of the specification and for builders of Rialto tooling are documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Section titled “[Unreleased]”The first version, slice 0: the whole contract format 1.0.0 with its JSON Schema, the rules every generator follows, and the test contracts that check a tool against them. What each section means for generated code comes with the profile of its slice.
Specification
- The overview, core and the contract format. Core defines the terms and the rules every generator follows (C1–C8).
- Every requirement has a stable id, such as
K1.2, so tools, tests and findings can cite it. Requirements use MUST, SHOULD and MAY (BCP 14). - Every document ends with the rationale for its choices, including the alternatives that were rejected.
Contract format 1.0.0
- A JSON Schema for every section:
spec/contract-1.0.0.schema.json, also served athttps://rialto.buijs.dev/spec/contract-1.0.0.schema.json. Point your editor at it for completion and checks while you write a contract. - Types (K2): every type has exactly one JSON form on the wire. Decimals, date-times, durations, map keys, extensible
enums, discriminated unions, and
jsonandbinaryfor free-form and binary data. - Every number in a contract (
maxLength,maxItems,maxSize, …) is a 32-bit signed integer, at most 2147483647, so every language can hold it. descriptionin CommonMark on types, properties, shapes, operations, events and error codes (K3).- Sources (K4): a contract points into OpenAPI, AsyncAPI and SQL documents instead of repeating them. A SQL source can
be the migrations of a service, applied in version order (K1.9). Remote sources are pinned by hash in
rialto.lock; a lock that cannot be read or written is an error (RIALTO-K010), never an empty lock. - Contracts over several files (K5): a root lists its fragments under
include, and they merge by name into one bundled document. - Extension keys
x-<generator>-<name>for the settings of one generator (K1.8). - Standard diagnostic codes (K1.10):
RIALTO-K…for the format,RIALTO-S…for sources andRIALTO-P…for the rules of the profiles. Every tool reports the same code for the same problem. The table lists every code already; thePrules come with their profiles.
Checking a tool
- Test contracts in
examples/contracts: valid contracts that must pass, and invalid ones that each name the codes they must produce. They cover documents that are not a mapping, schema violations, unsupported versions, unresolved references, duplicate names, invalid map keys, missing sources, an unusablerialto.lockand contracts over several files. tools/conformance.pyruns any tool over the test contracts and reports per contract whether it passed, so anyone can repeat a claim of conformance.tools/compare_tools.pycompares the findings of two tools in detail: file, severity, code, pointer and requirement.- The test contracts, the JSON Schema and
contract.mdare published together asdev.buijs.rialto:rialto-spec, so a tool can test against a fixed version of them.
Project
- The site rialto.buijs.dev, built from this repository.
- Licensed under the Apache License 2.0.