Declared, inferred and synthesized

Some sources state an API outright. Others only show one: an .http file is a list of requests, a Postman collection has example bodies rather than schemas, and an Envoy route table is evidence of an API rather than a description of it. When Apiome imports one of these, part of what you see was inferred. Every catalog item labels each part, so you can tell what the source said from what Apiome worked out.

The three labels

Label	Meaning	Example
Declared	The source states it. This is the default and carries no badge.	A request in a Postman collection; an interface in a TypeScript module
Inferred	Apiome deduced it from an example, a sample or code.	A schema read from an example response body; a path template generalized from sample URLs
Synthesized	Apiome supplied it. The shape may come from the source, but the source never named it.	Order_lines_item, the name Apiome gives an anonymous object inside Order.lines

Each inferred or synthesized part also records its evidence: one sentence saying what produced it, such as Schema inferred from the example request body of POST /orders.

Which imports infer

Import	What is inferred or synthesized
HTTP request files (.http, cURL)	Everything is inferred from the requests in the file.
Hoppscotch collections	Everything is inferred from the saved requests in the collection: path templates, parameters and body schemas.
Thunder Client collections	Everything is inferred from the saved requests in the collection: path templates, parameters and body schemas.
SoapUI / ReadyAPI projects	A REST interface is inferred from its saved requests and mock responses. A WSDL interface is declared by its WSDL; when the WSDL is not uploaded, its operations are declared from the project.
Postman collections	Request and response schemas are inferred from example bodies. A raw body that is not JSON is synthesized as a string. Requests, paths and parameters are declared.
Envoy, Istio, Traefik, NGINX, HAProxy, Consul, Tyk Classic	Every route is inferred from the gateway configuration. A Tyk OAS document is declared.
Kong, Gateway API	Routes are declared. A path recovered from a regex pattern is inferred.
SHACL shapes, OWL / RDFS ontologies, JSON-LD contexts	Shapes, classes, properties and terms are declared. A type for an anonymous shape, a scoped context or a container map is synthesized. A class's individuals listed as an enum without owl:oneOf are inferred.
ROS 2 interfaces	Messages, services, actions and fields are declared. The enum that holds an interface's constants and an action's feedback channel are synthesized.
LwM2M / IPSO objects	Objects, resources and their units and ranges are declared. The Objlnk record an object-link resource is typed as is synthesized.
MQTT Sparkplug B payloads	Everything is inferred: a payload does not carry its topic, so its message type comes from the file name or its metrics. A namespace description is declared. A DataSet row record is synthesized.
TypeScript, Zod, tRPC, Pydantic, CUE, Pkl, Dhall	Types are declared. An anonymous type or a generic instantiation that Apiome names is synthesized, and so is the type that holds a tRPC procedure's inline input or output.

Every other import, such as OpenAPI, AsyncAPI, protobuf or GraphQL, is declared throughout.

See it on a catalog item

1. Open the catalog item from Bring in → Catalog.
2. On the Overview tab, scroll to the parsed entities. An inferred entity carries an Inferred badge and a synthesized one a Synthesized badge.
3. Hover a badge to read its evidence.
4. To see one kind only, choose Declared, Inferred or Synthesized in the Provenance filter above the entities. Each option shows how many entities it holds, and the line beside it states the inferred share of the whole item, for example 33% of this item's constructs are inferred (4 of 12) · 1 synthesized. Choose All to see everything again.

The Provenance filter appears only when the item has at least one inferred or synthesized entity.

Route/ade/dashboard/catalog/[id]

The share counts every service, operation, parameter, message, type and channel of the item, so it can differ from the entity counts in the filter. A parameter or message of an inferred operation counts as inferred too.

The inferred-share lint rule

The provenance.inferred-construct-ratio rule reports the same share as a lint finding on the item's Lint & score tab, for example 62% of this item's constructs are inferred (13 of 21). It appears only when at least one part is inferred, and it ships at info, so it costs a score one point at most.

Keep inferred APIs from being published

A catalog item is not published itself: you convert it to an OpenAPI Project and publish the Project. To refuse publishing a Project whose catalog source was partly inferred:

1. Duplicate the Apiome Recommended style guide (built-in guides are read-only).
2. In the copy, set provenance.inferred-construct-ratio to error.
3. Assign the guide to the Project, or to the whole workspace.

From then on, publishing a Project converted from a catalog item with any inferred part is refused with a style-guide error that names the source item and its inferred share. Import a declared source instead (for example an OpenAPI document for the same API), or force-publish with a reason. See Lint and quality.

With the API

GET /v1/catalog/{tenant_slug}/{item_id} returns the labels:

• each entity in parsed carries provenance (declared, inferred or synthesized) and provenanceEvidence;
• provenanceSummary carries the declared, inferred, synthesized and total counts and the inferredRatio.

See the catalog REST reference.

Related

• Catalog: the catalog item page and its tabs.
• Built-in lint rules: the rule's id, category and severity.
• Import Zod schemas, Import a tRPC router and Envoy and Istio route import: imports that label what they infer.