Skip to content

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.

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 at https://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 json and binary for 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.
  • description in 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 and RIALTO-P… for the rules of the profiles. Every tool reports the same code for the same problem. The table lists every code already; the P rules 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 unusable rialto.lock and contracts over several files.
  • tools/conformance.py runs any tool over the test contracts and reports per contract whether it passed, so anyone can repeat a claim of conformance.
  • tools/compare_tools.py compares the findings of two tools in detail: file, severity, code, pointer and requirement.
  • The test contracts, the JSON Schema and contract.md are published together as dev.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.