Extend every definition with identity and type properties, and mark
both as required.
Defaults add JSON-LD @type and @id. For Prisma, pass
PRISMA_SCHEMA_IDENTITY.typeKey and .idKey (or "type", "id").
Audience: schema authors (framework users), not framework internals
This is a public convenience for application code that hand-authors its
JSON Schema. It implements the convention "every definition IS a named
entity": instead of declaring @id / @type explicitly on each
definition, you write plain domain definitions and apply this shortcut once
before handing the schema to the framework. Do not confuse it with the
lower-level machinery it wraps (extendDefinitionsWithProperties),
which framework code uses with custom property generators and filters.
When to use it — and when not
Use it only if you author the JSON Schema yourself and intend every
definition to be an entity. Because the extension is applied blanket to
all definitions, any definition that was meant as a plain value object
(an address block, a quantity-with-unit, a nested config shape, …) is
silently promoted to a named entity: it gains a required identity key,
becomes a Concise Bounded Description (CBD) root, halts graph extraction
at its boundary, and becomes eligible for $meta grafting.
That makes this shortcut the wrong tool for schemas you do not 100%
control — anything generated upstream from Zod, LinkML, OpenAPI, or
another pipeline. Generated schemas usually mix entity definitions with
structural helper definitions, and blanket promotion produces wrong CBD
boundaries, spurious required-property validation errors, and entities
where none were modeled. For such schemas, either:
let the generator emit identity properties on exactly the definitions
that are entities (preferred — identity stays explicit in the source of
truth), or
call extendDefinitionsWithProperties directly and exclude
non-entity definitions via options.excludeSemanticPropertiesForType.
Keep identity keys aligned
Pair the chosen idKey with the same value in
entityIdentityFromIdKey / deriveExtendedSchema({ identityKeys })
so CBD detection and $meta grafting match the schema shape.
Extend every definition with identity and type properties, and mark both as
required.Defaults add JSON-LD
@typeand@id. For Prisma, passPRISMA_SCHEMA_IDENTITY.typeKeyand.idKey(or"type","id").Audience: schema authors (framework users), not framework internals
This is a public convenience for application code that hand-authors its JSON Schema. It implements the convention "every definition IS a named entity": instead of declaring
@id/@typeexplicitly on each definition, you write plain domain definitions and apply this shortcut once before handing the schema to the framework. Do not confuse it with the lower-level machinery it wraps (extendDefinitionsWithProperties), which framework code uses with custom property generators and filters.When to use it — and when not
Use it only if you author the JSON Schema yourself and intend every definition to be an entity. Because the extension is applied blanket to all definitions, any definition that was meant as a plain value object (an address block, a quantity-with-unit, a nested config shape, …) is silently promoted to a named entity: it gains a required identity key, becomes a Concise Bounded Description (CBD) root, halts graph extraction at its boundary, and becomes eligible for
$metagrafting.That makes this shortcut the wrong tool for schemas you do not 100% control — anything generated upstream from Zod, LinkML, OpenAPI, or another pipeline. Generated schemas usually mix entity definitions with structural helper definitions, and blanket promotion produces wrong CBD boundaries, spurious required-property validation errors, and entities where none were modeled. For such schemas, either:
options.excludeSemanticPropertiesForType.Keep identity keys aligned
Pair the chosen
idKeywith the same value in entityIdentityFromIdKey /deriveExtendedSchema({ identityKeys })so CBD detection and$metagrafting match the schema shape.