interface-canon/infospace/models/interface/InterfaceCanonInterfaceModel.md

---
id: interface-model
title: InterfaceCanon Interface Model
namespace: interface-model
type: domain-model
status: draft
version: 0.1.0
imports: [itc-land, itc-ident, itc-evid, itc-gov]
import_manifest: imports.json
source_manifest: ../../assimilation/fiam/sources.json
---

# InterfaceCanon Interface Model

Draft terminology derived from FIAM v0.2 Draft 6. These are domain definitions,
not a new FIAM schema or a claim of transferred ownership. The exact FIAM spellings
and source JSON pointers are recorded below. [Upstream mappings](../../mappings/upstream.md)
explain shared concepts and collisions; [imports.json](imports.json) pins InfoTechCanon.

## Structural vocabulary

Each source locator below is relative to `schemas/FIAM-Core-v0.2.schema.json`
in the [pinned FIAM package](../../assimilation/fiam/README.md).

### 1. Port

An owned architectural participation point through which a participant or system node offers or requires a particular interface contract.

An offer/require mode is contract participation, not message direction.

Source: `#/$defs/port`. Local identifier: `interface-model:port`.

### 2. Contract Participation

The association of a Port with a specific InterfaceContract, an offers/requires mode, and contextual roles.

Roles belong to the participation; a port-global role cannot describe every contract context.

Source: `#/$defs/contractParticipation`. Local identifier: `interface-model:contractParticipation`.

### 3. Interface Contract

A semantic agreement organizing operations and their purposes independently of any particular transport realization.

One contract can have multiple bindings; a specification file describes the contract.

Source: `#/$defs/interfaceContract`. Local identifier: `interface-model:interfaceContract`.

### 4. Operation

A named unit of interface behavior within a contract, qualified by interaction style, temporal semantics, effects, and purpose.

A runtime exchange selects or realizes an operation; the operation is not a trace occurrence.

Source: `#/$defs/operation`. Local identifier: `interface-model:operation`.

### 5. Binding

A realization of a contract and selected operations through participating ports, communication stack, addressing, discovery, and optional channel or endpoints.

A second transport can realize the same contract without creating new semantic operations.

Source: `#/$defs/binding`. Local identifier: `interface-model:binding`.

### 6. Endpoint

A concrete locator or selector through which a Binding is reached.

An endpoint may be reused by multiple bindings; it is not the information resource selected through that binding.

Source: `#/$defs/endpoint`. Local identifier: `interface-model:endpoint`.

### 7. Channel

An exchange or mediation locus characterized by delivery, ordering, replay, or retention semantics where known.

A Kafka topic as exchange channel may be backed by a retained-log resource; those roles remain distinct.

Source: `#/$defs/channel`. Local identifier: `interface-model:channel`.

### 8. Interaction

An architectural participation in an exchange linking relevant operation, contract, binding, participants, and channel, with realization status where known.

An interaction can be proposed or rejected; do not equate every interaction with an executed span.

Source: `#/$defs/interaction`. Local identifier: `interface-model:interaction`.

### 9. Interaction Flow

An ordered composition of exchange steps referring to operations, interactions, bindings, and participants.

It expresses composition rather than inventing a new protocol or contract family.

Source: `#/$defs/interactionFlow`. Local identifier: `interface-model:interactionFlow`.

### 10. Information Resource

An identifiable information-bearing object, state, collection, or logical selection that can be addressed independently of a single interaction.

A collection is a resource; its admissible form is a shape, and its access location is not automatically a binding endpoint.

Source: `#/$defs/informationResource`. Local identifier: `interface-model:informationResource`.

### 11. Information Shape

An identifiable semantic or structural type or constraint set describing an admissible information form.

A shape is distinct from an instance, a schema artifact, and JSON or another concrete encoding. Detailed fields remain in describing artifacts.

Source: `#/$defs/informationShape`. Local identifier: `interface-model:informationShape`.

### 12. Resource Selector

A selector identifying an information resource within a provider, namespace, collection, or logical address space.

A database collection selector does not locate the network binding.

Source: `#/$defs/resourceSelector`. Local identifier: `interface-model:resourceSelector`.

## Facets and interpretations

A **Facet** records an orthogonal characteristic of a structural entity or assertion.
FIAM uses controlled terms for such dimensions as interaction style, temporal
semantics, effect, purpose, communication stack, and security. A facet is not a
new structural interface type. Source: Core `#/$defs/facets` and the FIAM Canon.

**Representation** is the concrete encoding or notation selected for information
participation. It is authoritative on the most specific applicable shape-participation
assertion. Operation-level and contract-level representation lists are deprecated.
Source: Draft 1, “Representation stays relation-scoped”.

A **Lens** is a named interpretation over architectural facts and their evidence.
**Family labels** are derived lens results, with inferred provenance if cached;
HTTP, RPC, messaging, or a label such as REST must not become invented Core classes.
Source: Draft 1, “Cached family labels require provenance”; Draft 6 §§1, 6–7.

## Relationships and invariants

- A Port participates in a contract; a Binding realizes that contract and its operations.
- Shape participation refines Operation → Binding → Interaction. Refinement uses
  the same shape, identity-equivalent shape, or evidenced projection/version.
  Multi-operation binding refinements identify the operation with `operation_ref`.
- `conforms-to-shape` describes the whole addressed resource; `element-shape`
  describes collection members. A collection's shape and its element shape differ.
- Artifacts describe or implement architectural entities; representation encodes information.
- Missing facts remain unknown. Explicit absence, not-applicable, and unknown differ.
- Similarity supports correspondence, not automatic identity or destructive merging.
- Lens evidence scores and governance conclusions remain policy-dependent results.

Sources: Draft 1 “Stable structural spine” and hardening decisions 3–7;
Core `assertion`; Draft 6 §§1, 6–7. These summaries preserve source semantics;
FIAM remains authoritative for exact validation requirements.

## Worked boundary cases

| Case | Interpretation |
| --- | --- |
| Same MCP tools over stdio and HTTP | Shared contract/operations/shapes; distinct realization bindings. |
| Kafka topic with retained events | Channel for exchange, Information Resource for retained log, related by `backed-by`. |
| JSON document governed by a schema | Resource instance, Information Shape, describing Artifact, and Representation remain distinct. |
| Port offers a request-response contract | Offers is participation mode; requests and responses still travel in different directions. |
| Two schemas have identical fields | Correspondence candidate; no automatic identity assertion. |
| Telemetry contains no authentication attributes | Unknown runtime authentication evidence; no inferred absence of protection. |

These are explanatory cases derived from the pinned source, not executable FIAM
fixtures or evidence of consumer adoption. Cross-canon review and a consumer proof
are tracked in INTERFACE-WP-0003.