facetted-interfaces/history/FIAM_v0.2_Draft6/policies/FIAM-ShapeIdentity-v0.2.md

FIAM v0.2 — InformationShape Identity Policy

Purpose

FIAM treats InformationShape as an architectural identity node, not as a schema document and not as a wire-format label. This policy governs when separately discovered descriptions should be represented as one shape, multiple related shapes, or unresolved candidates.

Identity rule

Two observations may refer to the same InformationShape when they are intended to describe the same admissible semantic/structural form even if they originate in different artifacts, languages, bindings, or representations.

Examples: one Customer shape described by OpenAPI and standalone JSON Schema; the same Product shape encoded as JSON and CBOR; a Java declaration and an API schema that an authoritative source explicitly maps to the same contract type.

New shape rule

Create a distinct shape identity when a structural/constraint difference matters to the architecture, when a shape is intentionally versioned, or when a projection/subset/view exposes a different admissible form. Use version-of for lineage and projection-of for intentional views/projections.

Do not mint a new shape merely because another artifact describes it or another representation carries it.

Uncertain reconciliation

Independent ingest sources should not immediately use same-entity-as. Prefer corresponds-to or observationally-equivalent-to while identity is uncertain. Promote to evidence-backed same-entity-as only when there is sufficient authoritative evidence.

same-entity-as, alias-of, version-of, and observationally-equivalent-to require subject and object to have the same FIAM entity kind. Identity assertions never delete source entities or evidence; repository reconciliation is a separate operation.

Resource and shape

A stable InformationResource can change shape over time. Preserve separate shape identities with validity windows rather than overwriting history. A collection-like resource may conforms-to-shape a collection shape and separately use element-shape for its members.

Artifact, representation, and shape

• Artifact: concrete declaration/implementation (openapi.yaml, .proto, DDL, Java source).
• Shape: logical admissible form.
• Representation: JSON, protobuf, command tokens, native object, etc.
• Resource: identifiable information-bearing locus/state/collection.

These identities must not be collapsed.

Operational query semantics (draft.1)

An asserted same-entity-as edge places the participating IDs in one query-time equivalence class. It does not physically merge records. Traversal or presentation layers may collapse the class for convenience, but must retain and expose the original IDs and their evidence.

corresponds-to and observationally-equivalent-to do not create identity equivalence classes.

Operational promotion guard (draft.1)

Automated tools must not promote structural or fingerprint equality directly to same-entity-as.

Default behavior:

1. create corresponds-to for plausible matches;
2. accumulate independent evidence;
3. require a governed/authoritative identity decision for normal promotion;
4. if same-entity-as is asserted purely from inferred evidence, require at least two independent signals at confidence >= 0.98;
5. even when that inferred threshold is met, default tooling must not auto-promote without reconciliation policy/authority.

The validator operationalizes the minimum inferred-evidence guard. tools/identity_view.py operationalizes non-destructive query equivalence and candidate reporting.