APIs
7 pages.
| Page | First line | Links | |
|---|---|---|---|
| Canonical model | dist/model.json, the single file that describes the whole model: every later step reads it and none re-reads the sources. It is described by model.schema.json, published with the core package, and holds five blocks plus the two neighbourhoods: build, the only dated block, with the tool version, the timestamp, the fingerprint of the merged profile, one entry per source with its commit, whether links across sources were resolved and the contracts imported; entities, one object per note with its identifier, type, title, locale, application, domain, type origin, attributes and source; links, one object per source, target and relation triple with its combined confidence and every provenance; findings, the same array as the build log; candidates, the recurring expressions, the schemas of the imported contracts and the pairs of twin resources; neighbours, the best co-occurrence neighbours per entity; displayed_neighbourhood, the one-hop neighbours shown on every page. Keys are sorted at every depth, and a model read back refuses anything the schema does not describe. | 52 | |
| Plugin API | The versioned interface through which a plugin contributes to the tool: readers for file formats, converters, sources of entities such as contract importers, inference methods, checks, projections, user interface components, themes and types, each type a module folder merged into the profile. A plugin exports a manifest validated by the published schema, plugin.schema.json of the core package, which is a JSON schema and not a contract the build imports, so this note declares none; it is declared in the configuration and loaded in order into a deterministic registry. A plugin whose system dependency is missing disables itself with a finding. | 49 | |
| Model query API | The HTTP face of the future long-running service: it answers questions about the model of the last build for the screens that cannot read model.json directly. Nothing of it exists in the command line of this version; the contract, an OpenAPI 3.1 document kept next to this note, declares four operations, listEntities (GET /entities), getEntity (GET /entities/{id}), searchModel (GET /search) and listFindings (GET /findings), and four schemas, Entity, Link, Finding and SearchHit. The build imports the operations as operations of this API and attaches to each one the operation note that describes it, following the operation matching rule; an operation left without a note, listFindings today, keeps the properties of the contract only, and a note the contract does not declare yet, suggest links, stays ahead of it until the next version. The API page states both gaps and shows the contract in its viewer. | 44 | |
| List the entities | Returns the entities of the last build, in identifier order, with the same fields as the entities block of the model; a screen that cannot read model.json directly will page through them here. The operation is declared by the OpenAPI contract of the model query API and exists nowhere else in this version. | 35 | |
| Suggest links | Proposes the links a note could write, from the candidates of the last build: the objects a contract names without a note and the expressions the scan recognised without a definition. The model query API does not declare the operation yet: this note is ahead of its contract, which the operation unmatched rule reports until the contract catches up, and the API page lists it among the gaps, described, absent from the contract. | 21 | |
| Get an entity | Returns one entity of the last build by its identifier, with its attributes, its displayed neighbourhood and the links it is an end of, as the entity page shows them. Declared by the OpenAPI contract of the model query API; nothing of it exists in the command line. | 13 | |
| Search the model | Returns the entities matching a query, scored as the search island of the site scores them, for a client that does not load the search index. Declared by the OpenAPI contract of the model query API; the static search of the site does not depend on it. | 12 |
7 apis of 7 — pagination by twenty. The Links column counts the related pages, which brings the most central apis of the journey to the top.