facetted-interfaces/history/FIAM_v0.2_Draft6/OPENAPI-INGEST-v0.2.md

FIAM v0.2 — OpenAPI Declared-Ingest Profile (draft.4)

Intent

Turn an OpenAPI 3.x description into a FIAM declared architecture model while preserving the distinction between architectural entities and the source artifact.

The importer is architecture-oriented, not a lossless OpenAPI converter. Detailed schema semantics remain in the OpenAPI Artifact.

Mapping

OpenAPI construct	FIAM expression
API document	Artifact (fiam.artifact.api-description)
API/service	SystemNode + offered Port + InterfaceContract
path + HTTP method	Operation
server URL	Endpoint
HTTP realization	Binding + communication stack
path template	logical-selection InformationResource
component or inline schema	InformationShape
response/request schema	Shape-participation relations
media type	relation-scoped representation
object/array composition	coarse embeds-shape / element-shape
source location	assertion Evidence locator
HTTP method	declared property assertion
generic HTTP family	declared communication-protocol assertion
components.securitySchemes	FIAM Security profiles
top-level / operation security	contract/operation Security requirements

Evidence

Relations and material property facts emitted from OpenAPI carry declared evidence with the source Artifact and JSON-pointer locator.

Observer:

openapi-ingest/v0.2-draft.4

Transport conservatism

An https:// server URL declares secure HTTP addressing. It does not determine TCP versus QUIC, because the OpenAPI document normally does not state the negotiated HTTP version/transport.

Draft.4 therefore emits:

HTTP
TLS

for an HTTPS declaration, but does not infer TCP.

This preserves the transport-conservative behavior introduced after draft.1.

Shape identity

The importer reuses a FIAM Shape for repeated references to the same OpenAPI component identity. Different components remain distinct even when structurally identical.

Structural fingerprint equality emits only:

Shape A --corresponds-to--> Shape B

never automatic same-entity-as.

Current scope

Supported:

• OpenAPI 3.x YAML/JSON;
• component and common inline Shapes;
• coarse shape composition;
• request/response shape participation;
• common representations;
• server endpoints and HTTP/TLS stack;
• path-template Resources;
• evidence-backed HTTP method and generic protocol facts;
• structural-fingerprint candidate alignment;
• local OpenAPI security schemes and Security Requirement composition (see OPENAPI-SECURITY-INGEST-v0.2.md).

Not yet a goal:

• lossless parameter/schema conversion;
• complete external $ref resolution;
• full callback/webhook flows;
• automatic identity merge;
• schema fields in FIAM Core.