Contract import scope review

Meeting53 minPseudonymised participants

Grouped automatically

01:12
Participant-1 — Let us start with the scope. The question is what the contract import reads, and what it leaves to the notes.
04:22
Participant-2 — Today an api note lists its operations by hand. When it declares a contract, the build reads the contract and produces one operation per operation id.
08:22
Participant-3 — And when a note already exists for that operation? We have three operation notes under the model query api.
11:47
Participant-2 — The operation matching rule attaches the contract operation to the note that names the same operation id, or the same method and path. The note absorbs it; the imported operation does not exist twice.
16:57
Participant-1 — So the operations table on the api page comes from the contract, and each row links to the note when one matches. What about an operation nobody wrote about?
21:17
Participant-2 — It stays an operation of the api with the properties of the contract only, and the operation unmatched check reports it, as a warning, so that someone writes the note.
26:02
Participant-3 — From the integrator's side, the contract file lives next to the note. Relative path, under contracts, and the fingerprint cache keeps the parsed text between two builds.
31:32
Participant-1 — Now the viewer. The specification named an interactive console for openapi contracts. It weighs more than the page budget, and it wants to call the api from the page.
35:32
Participant-2 — The site is static and reads from the disk. A console that fetches the contract over the network breaks that on the first page it is used on.
39:07
Participant-3 — Agreed. What readers need is the list of operations, their method and path, the schemas, and a link to the note. Nothing that calls anything.
42:17
Participant-1 — Then the decision of this session: a purpose-built contract viewer, an island rendered from a json fragment of the contract, loaded on demand, under the page budget. Participant-3 writes the decision note.
Decision taken here Purpose-built contract viewer
45:12
Participant-3 — I will, under the publication decisions. And the schemas become candidate objects, as Participant-2 said, so the to-do page lists them.
48:52
Participant-2 — One more thing for the record: a contract that cannot be fetched or parsed yields the contract unreachable finding and the note keeps its hand-written operations. The build never stops on it.
53:12
Participant-1 — Good. Findings, not failures. That closes the scope of the contract import for this version.
Decision taken here Findings, not failures

The names of the participants are replaced at publication by stable pseudonyms. The mapping is never published.

Working session (note: Meeting) on what the contract import (note: Contract) reads and what it leaves to the notes (note: Note). Three participants: the maintainer (3 passages, no note), an author of the specifications (3 passages, no note) and the integrator (note: Integrator) of the wiki. The transcript of the session (3 passages, no note) sits next to these minutes and the build (note: Build) shows both on one page.

What was said

An API note (note: API) that declares a contract gets one operation per operation (4 passages, no note) of the contract; the operation (4 passages, no note) matching rule (4 passages, no note) attaches each one to the operation note (note: Operation) that names the same operation id (3 passages, no note), or the same method (28 passages, no note) and path. The note absorbs the imported (27 passages, no note) operation, which never exists twice.
An operation nobody wrote about keeps the properties (note: Attribute) of the contract only and is reported by the operation unmatched (note: Operation unmatched) check (note: Check), a warning, so that someone writes the note.
The contract file lives next to its note, under contracts/, and the fingerprint cache (note: Fingerprint cache) keeps its parsed (7 passages, no note) text between two builds.
A contract that cannot be fetched or parsed yields the contract unreachable (3 passages, no note) finding (note: Finding); the note keeps its hand-written operations and the build goes on.

Decision

The interactive (15 passages, no note) console (6 passages, no note) the specification (15 passages, no note) named for OpenAPI contracts is not used: it weighs more than the page budget (20 passages, no note), expects to fetch the contract over the network and offers to call the API from the page. The contract of an API is shown by a purpose-built contract viewer (note: Purpose-built contract viewer), an island (note: Island) rendered (33 passages, no note) from a JSON fragment (note: Fragment) of the contract, loaded on demand. The schemas (31 passages, no note) of the contract become candidate objects (4 passages, no note), listed on the to-do page (note: To-do page).

Properties

Date: June 18, 2026
Duration: 53 min
Space: Briefs
Domain: Ingestion

2 files grouped — declared in frontmatter

contract-import-scope.mdMarkdown note
contract-import-scope.vttVTT

Separate these files

2 files: same folder, same base name, declared in the frontmatter.

See the neighbourhood map6 pages6Neighbourhood mapContract import scope review

Neighbourhood map Contract import scope review

Distance1 hop

existing pageword without a note

35 neighbours in total, more than the map shows.

The 6 neighbourstextual equivalent

Purpose-built contract viewerDecisiondocuments1
Findings, not failuresDecisiondocuments1
ContractTermdocuments1
OperationTermdocuments1
NoteTermdocuments1
APITermdocuments1

Six neighbours at most, always named. Beyond that the map teaches nothing: the list takes over.