# 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:

```text
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:

```text
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:

```text
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.