How profile gaps are computed
The function that derives ΔIRI / ΔICI, the rules for additive vs substitutive items, and the edge cases the comparison handles.
computeProfileGap() — the underlying function
Gap analysis is a pure function over two published competency profiles: the organisation-scoped one (subject) and the canonical future-ready one (target). It returns a structured ProfileGapPackage with five sections — item deltas, added items, removed items, information-use deltas, and substitutions — plus a summary aggregate.
ΔIRI — Information Requirement Index delta
IRI ranges from 0 to 3 per item per profile. The delta is target.iri − subject.iri. A positive delta means the canonical demands more information for that item than your profile does; a negative delta means your profile demands more. Per-item deltas are summed into the iriGapTotal for the summary bar.
ΔICI — Information Competency Index delta
ICI ranges from 0 to 3 per item per profile. The delta is target.ici − subject.ici. A positive delta means the canonical demands more competency depth (a higher cognitive / execution bar) for that item. Per-item deltas are summed into the iciGapTotal.
Additive vs substitutive items
If an item appears on the canonical side but not on the subject side, it is classified as missing (substitutive — the subject needs to add it). If it appears on the subject side but not on the canonical side, it is classified as extra (additive — the subject has a local specialism). "Substitutive" here means the absence of an item that the canonical requires; it is distinct from the material substitutions section, which tracks cited-material swaps.
Information-use changes
Each item carries information-use links with a relevance tier. The IU section reports three lists: changedIus (same IU, different relevance), addedIus (present on subject, not on canonical), and removedIus (present on canonical, not on subject).
Material substitutions
Substitutions are jurisdiction-driven. The canonical may cite ISO 19650; the org's jurisdiction may substitute ABNT NBR ISO 19650 (BR), IS EN ISO 19650 (IE), or CSA Z250 (CA). The substitution is not a gap — it is a localisation choice the canonical materials registry blesses. The substitutions section lists each canonical reference, its accepted local equivalent, and an optional note.
Edge cases
- An item with no IRI on either side renders as "—" and contributes 0 to the iriGapTotal.
- An item with no ICI on either side renders as "—" and contributes 0 to the iciGapTotal.
- Comparing a profile to itself returns the self-compare empty state — the comparison is not meaningful.
- If no canonical exists for the jurisdiction, the empty state offers a sponsorship or verification-panel CTA — see the journey doc.
- Drafts are excluded. Both sides must be published for the gap to compute.
Stability tier
The gap package schema is at stability tier beta. The shape may evolve in minor versions until 1.0; breaking shape changes will bump the schemaVersion in the package envelope and the change will be called out in the change log.
