tegwick
1353267569
Assistant: codex Assistant-Model: gpt-5.6-luna Assistant-Session: 01a087b0-7b1e-7531-8ef3-6525ebaf7ee7
87 lines
2.8 KiB
Markdown
87 lines
2.8 KiB
Markdown
# 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.
|