Purpose

Marks draft|active → approved: the key is vetted and canonical. Approve requires a parameter spec and a parameter control, which is why parameterSpecId and parameterControlId are non-nullable here and nullable on every other ParameterKey* event. BIM usage is not required.

When the approved key carries usage:bim_parameter, this is the lifecycle event that mints Revit state. Catalog-only keys stay without a projection.

Payload

Envelope is { name, occurredAt, payload } (apps/api-v1/src/modules/shared/domain/events/DomainEvent.ts).

Field	Type	Meaning
parameterKeyId	ParameterKeyId	Key that was approved
handle	string	Normalized dictionary slug; also drives the built-in vs shared projection policy
name	string	Canonical label
parameterSpecId	string	Value semantics — required to approve
parameterControlId	string	Presentation — required to approve
parameterGroupId	string | null	Authoring group; optional at every stage
approvedAt	Date	When approval happened; part of the handler’s idempotency key

Raised by

• ParameterKey.approve — apps/api-v1/src/modules/bim-ontology/core/domain/parameter-key/ParameterKey.ts
• ApproveParameterKeyUseCase.approveParameterKey — apps/api-v1/src/modules/bim-ontology/core/application/use-cases/ParameterKeyAuthoringUseCases.ts
• HTTP: approveParameterKey

Consumers

ParameterKeyApprovedProjectionHandler (adapters/inbound/events/), registered in bim-ontology.composition.ts, calls EnsureRevitProjectionForParameterKeyUseCase.ensureRevitProjectionForParameterKey. The ensure path:

• skips keys without usage:bim_parameter, so catalog-only keys never reach Revit;
• reuses an existing archived projection instead of minting a second one, preserving the shared parameter GUID;
• otherwise creates a draft projection — built-in or shared, per CommonParameterProjectionPolicy on the key’s handle.

The handler is idempotent on parameterKeyId + approvedAt and records failures through ForRecordingBimOntologyHandlerFailure before rethrowing.

Approval is the only trigger. There is no registration for ParameterKeyCreated or ParameterKeyActivated anywhere in the module.

Related

• ParameterKey, RevitParameterProjection
• RevitParameterProjectionCreated, RevitParameterProjectionReused
• ParameterKeyUpdated — the repair path for a missing projection