coulomb/facetted-interfaces
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
facetted-interfaces/history/FIAM_v0.2_Draft6/MIGRATION-v0.1.1-to-v0.2.md
tegwick 1353267569 Establish FIAM repository governance baseline 
Assistant: codex
Assistant-Model: gpt-5.6-luna
Assistant-Session: 01a087b0-7b1e-7531-8ef3-6525ebaf7ee7
2026-09-09 21:53:43 +02:00

3 KiB
Raw Blame History

FIAM Migration — v0.1.1 to v0.2

Structural additions

Add information_resources[] and information_shapes[] when the architecture contains independently meaningful information loci or admissible information forms.

Do not add them mechanically to every interface. Incomplete models remain valid.

InformationShape

shape_kind is required for v0.2 shapes. Use fiam.information-shape.object for structured named-member forms; the experimental record term is deprecated.

Keep fine-grained members and constraints in schema/type Artifacts (OpenAPI, JSON Schema, protobuf, GraphQL, DDL, source declarations). FIAM Core identifies and relates the shape; it does not reimplement those schema languages.

Representation

Remove authoritative use of contracts[].representations and contracts[].operations[].representations. These fields remain parseable only to support migration and produce warnings.

Attach representation to the most specific shape-participation relation: Operation for a semantic default only when appropriate, Binding for a realization, Interaction for what actually occurred.

Shape relations

Use:

  • accepts-shape
  • produces-shape
  • errors-with-shape
  • conforms-to-shape
  • element-shape
  • embeds-shape

Binding-level shape participation on a Binding with multiple operations requires facets.operation_ref.

Shape composition

embeds-shape and element-shape may carry facets.slot and facets.role. These are coarse architectural anchors, not a replacement for field-level schema definitions.

Evidence

All v0.2 Assertions require evidence. Preserve conflicting/superseded assertions rather than overwriting discovery history.

Identity

Follow policies/FIAM-ShapeIdentity-v0.2.md. Prefer corresponds-to while two discoveries are only candidate matches. Use same-entity-as only with sufficient evidence. Identity assertions do not delete source records.

Specimen tests

v0.2 tests.expected_properties are executable checks. Move narrative expectations to tests.notes.

draft.1 hardening notes

Family labels

Do not manually carry forward family_labels as authoritative classifications. Either remove them or back each cached label with an inferred fiam.property.family-label assertion produced by a Lens. The validator rejects unproven family-label caches.

Shape refinement

When migrating shape participations, verify Operation → Binding → Interaction refinement. A lower-level Shape must be the same/equivalent Shape or be related by projection-of / version-of to the parent declaration.

Collection coherence

Collection-like InformationResources that use conforms-to-shape should point to a collection Shape. Use a separate element-shape relation for member shape.

Identity

Do not convert similarity heuristics into same-entity-as. Ingest/reconciliation tools should emit corresponds-to until sufficient governed identity evidence exists. Purely inferred same-entity-as is rejected unless the current Canon evidence threshold is met.