defineEntityKind
Registers a new entity kind in the dynamic-ontology registry after an automatic semantic dedup check, reusing an existing kind or recording a close-match alias to prevent synonyms.
Instructions
Register a new entity kind in the dynamic-ontology registry — but first check whether an existing kind already covers the concept (introspect → entityKinds, or describeType). The built-in dedup check runs automatically: a near-identical kind returns status="reused" with the existing name so you avoid minting a synonym; a medium-similarity near-duplicate mints but records a SKOS closeMatch alias (response field closeMatch + similarity, internal URN maz:kind: added to sameAs). Because that dedup runs a semantic embedding pass over existing kinds, this call routinely takes a few seconds to return — that latency is expected, not a hang; do not abort or retry on a short timeout. Inputs: name (bare snake_case, no namespace), displayName, description (required for dedup), optional extends (parent kind — must be a core kind or an already-registered active kind; bare names resolve to their canonical registered form), sameAs (external vocabulary IRIs), propertySchema (JSON Schema for typed attributes). Appends an entityKindRegistered event; the dispatcher materialises it into entity_kinds and the render pipeline writes it to the git-synced ontology/ tree. Re-registering an existing user kind with force=true overwrites it. Attempting to modify a core kind, or extending an unknown/ambiguous parent, returns E_VALIDATION.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Bare snake_case kind identifier, e.g. vehicle. No namespace prefix — user: is added automatically. Must not start with core:. | |
| force | No | Bypass the reuse-before-mint dedup check and register unconditionally. Default false. | |
| sameAs | No | Alias/sameAs IRIs to canonical external vocabularies, e.g. ["schema.org/Vehicle", "wikidata:Q42889"]. Optional. | |
| extends | No | Parent kind name for single-inheritance subtype hierarchy (RDFS subClassOf). Must be a core kind or an already-registered active kind; a bare name (vehicle) resolves to its canonical registered form (user:vehicle) when unambiguous. E_VALIDATION when unknown or ambiguous. Optional. | |
| preview | No | When true, compute and return a plan of what this call would do (collapse, supersede, or mint) WITHOUT appending any event. The event log is unchanged. Use this to inspect impact before committing. Default false. | |
| description | Yes | One-sentence explanation of the kind. Used by the dedup check and agents. | |
| displayName | Yes | Human-readable label, e.g. Vehicle. | |
| propertySchema | No | Optional JSON Schema (Draft 2020-12) for typed attributes. Compiled before registration; E_VALIDATION on compile failure. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The registered kind name, e.g. user:vehicle. | |
| plan | No | Present only when preview=true. Describes what the call would do without writing any event. | |
| status | Yes | registered = kind written as active; reused = existing near-identical kind returned instead of minting; proposed = kind queued for review in governed mode; preview = plan computed without writing any event (preview=true was set). | |
| warnings | No | Non-fatal advisory warnings. MAZ-KIND-001 = close match found; MAZ-KIND-002 = semantic dedup skipped; MAZ-SCHEMA-001 = supersede; MAZ-SCHEMA-002 = orphaned fields; MAZ-SCHEMA-003 = collapse. | |
| closeMatch | No | The name of a closely related existing kind (skos:closeMatch semantics). Present when a medium-similarity near-duplicate was found during minting. | |
| reusedKind | No | The existing kind name when status=reused. Absent otherwise. | |
| similarity | No | Dedup similarity score (0..1). Present when status=reused or when closeMatch is set. |