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