Resource Governance API: schemas

The request and response bodies of the operations in this API.

ActivateRetentionChoiceRequestDto

Property	Type	Required
`assignmentKey`	string	yes
`assignmentRevision`	number	yes
`bundle`	RetentionBundleRefDto	yes
`effectiveFrom`	string (date-time)	yes
`effectiveUntil`	string (date-time) or null	yes
`expectedPointerRevision`	string	yes
`priority`	number	yes
`reason`	string	yes
`sourceRef`	string	yes
`target`	OrgRetentionChoiceTargetDto	yes

EffectiveRetentionDto

Property	Type	Required	Description
`apiVersion`	one of `"xema.retention/v1"`	yes
`ceilingDays`	number or null	yes	`null` means no rule of that role applies, NOT "unbounded".
`chosenDays`	number or null	yes
`clamped`	boolean	yes	True when the live bounds moved the chosen window.
`configured`	boolean	yes
`effectiveDays`	number or null	yes
`floorDays`	number or null	yes	`null` means no rule of that role applies, NOT "unbounded".
`kind`	one of `"effective_retention"`	yes
`orgId`	string	yes
`policyWatermark`	string	yes
`provenance`	RetentionProvenanceDto	yes
`resolvedAt`	string (date-time)	yes
`subjectClass`	one of `"agent_session"`, `"artifact"`, `"app_run"`, `"notification"`, `"activity_feed_entry"`, `"search_trace"`, `"workload_record"`, `"audit_entry"`	yes

EffectiveRetentionDtoDataEnvelope

Property	Type	Required	Description
`data`	EffectiveRetentionDto	yes

GovernanceRecordDto

Property	Type	Required	Description
`value`	object	yes	Versioned resource-governance result.

GovernanceRecordDtoDataEnvelope

Property	Type	Required	Description
`data`	GovernanceRecordDto	yes

GovernanceRowDto

One versioned resource-governance row.

Type: object

GovernanceRowDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of GovernanceRowDto	yes

InventoryItemDto

Property	Type	Required	Description
`definitionId`	string	yes
`definitionKey`	string	yes
`definitionRevision`	number	yes
`dimensionsJson`	object	yes
`generation`	number	yes
`id`	string	yes
`lifecycle`	one of `"present"`, `"retired"`	yes
`observedAt`	string (date-time)	yes
`orgId`	string	yes
`parentResourceRefsJson`	array of string	yes
`producerId`	string	yes
`quantityValue`	string	yes	Canonical exact decimal string.
`reservedQuantityValue`	string	yes	Canonical exact decimal string.
`resourceRef`	string	yes
`retiredAt`	string (date-time) or null	no
`scopePathJson`	object	yes
`sourceRef`	string	yes
`unit`	string	yes

InventoryItemDtoPaginatedEnvelope

Property	Type	Required	Description
`data`	array of InventoryItemDto	yes
`pagination`	PaginationMeta	yes

LegalHoldOrgScopeDto

Property	Type	Required	Description
`kind`	one of `"org"`	yes	Freeze EVERYTHING for the organization.

LegalHoldRecordDto

Property	Type	Required	Description
`apiVersion`	one of `"xema.retention/v1"`	yes
`holdId`	string	yes
`kind`	one of `"legal_hold"`	yes
`matterRef`	string	yes	A stable reference to the matter (case number, ticket, order) this serves.
`orgId`	string	yes	The organization whose data is frozen. A hold never spans organizations.
`placedAt`	string (date-time)	yes
`placedBy`	string	yes
`reason`	string	yes
`releaseReason`	string or null	yes
`releasedAt`	string (date-time) or null	yes
`releasedBy`	string or null	yes
`scope`	LegalHoldOrgScopeDto or LegalHoldSubjectClassScopeDto or LegalHoldSubjectScopeDto	yes	How wide the hold reaches. Discriminated on `kind`; the three variants are an organization-wide freeze, a class-wide freeze, and a freeze on one named aggregate.
`state`	one of `"active"`, `"released"`	yes

LegalHoldRecordDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of LegalHoldRecordDto	yes

LegalHoldRecordDtoDataEnvelope

Property	Type	Required	Description
`data`	LegalHoldRecordDto	yes

LegalHoldSubjectClassScopeDto

Property	Type	Required	Description
`kind`	one of `"subject_class"`	yes	Freeze one kind of data organization-wide.
`subjectClass`	one of `"agent_session"`, `"artifact"`, `"app_run"`, `"notification"`, `"activity_feed_entry"`, `"search_trace"`, `"workload_record"`, `"audit_entry"`	yes

LegalHoldSubjectScopeDto

Property	Type	Required	Description
`kind`	one of `"subject"`	yes	Freeze one named aggregate.
`subjectClass`	one of `"agent_session"`, `"artifact"`, `"app_run"`, `"notification"`, `"activity_feed_entry"`, `"search_trace"`, `"workload_record"`, `"audit_entry"`	yes
`subjectId`	string	yes	Opaque to this plane — whatever the owning service calls the aggregate.

ListOwnLegalHoldsRequestDto

Property	Type	Required	Description
`matterRef`	object	no
`state`	one of `"active"`, `"released"`	no

OrgResourceSummaryDto

Property	Type	Required
`inventoryFreshness`	array of ProducerFreshnessDto	yes
`openFindings`	number	yes
`presentResources`	number	yes
`usageFreshness`	array of ProducerFreshnessDto	yes

OrgResourceSummaryDtoDataEnvelope

Property	Type	Required	Description
`data`	OrgResourceSummaryDto	yes

OrgRetentionChoiceTargetDto

Property	Type	Required	Description
`scopeKind`	one of `"org"`, `"project"`, `"user"`, `"application"`	yes
`scopeRef`	string	yes

OrgRetentionDecisionRequestDto

Property	Type	Required
`at`	string (date-time)	no
`scopePath`	array of RetentionDecisionScopeSegmentDto	yes
`subjectClass`	one of `"agent_session"`, `"artifact"`, `"app_run"`, `"notification"`, `"activity_feed_entry"`, `"search_trace"`, `"workload_record"`, `"audit_entry"`	yes

PaginationMeta

Property	Type	Required
`hasMore`	boolean	no
`limit`	number	no
`nextCursor`	string or null	no
`page`	number	no
`previousCursor`	string or null	no
`total`	number	no
`totalPages`	number	no

PlaceOwnLegalHoldRequestDto

Property	Type	Required	Description
`matterRef`	string	yes
`reason`	string	yes
`scope`	LegalHoldOrgScopeDto or LegalHoldSubjectClassScopeDto or LegalHoldSubjectScopeDto	yes	How wide the hold reaches. Discriminated on `kind`; the three variants are an organization-wide freeze, a class-wide freeze, and a freeze on one named aggregate.

ProblemActionableBy

Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.

Type: one of "user", "org-admin", "platform", "none"

ProblemDetailsDto

RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	string	yes	SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ProblemFieldIssueDto

Property	Type	Required	Description
`code`	string	no	SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem.
`detail`	string	yes	Prose for logs and developers. A frontend localises from `code` + `params` instead.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for this issue's `code`.
`pointer`	string	yes	RFC 6901 JSON Pointer into the request body. Root is "/".

ProblemRetry

What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.

Type: one of "transient", "after-change", "never"

ProducerFreshnessDto

Property	Type	Required
`completeness`	one of `"complete"`, `"partial"`, `"unavailable"`	yes
`observedThrough`	string (date-time)	yes
`producerId`	string	yes

ResourceDefinitionDto

Property	Type	Required
`aggregation`	string	yes
`apiVersion`	string	yes
`description`	string	yes
`dimensionsJson`	object	yes
`displayName`	string	yes
`id`	string	yes
`key`	string	yes
`lifecycle`	one of `"active"`, `"retired"`	yes
`measurementKind`	string	yes
`ownerVersion`	string	yes
`provenance`	object or object	yes
`quotaJson`	object	yes
`registeredAt`	string (date-time)	yes
`retiredAt`	string (date-time) or null	no
`revision`	number	yes
`sourceRef`	string	yes
`unit`	string	yes
`usageExportJson`	object	yes

ResourceDefinitionDtoPaginatedEnvelope

Property	Type	Required	Description
`data`	array of ResourceDefinitionDto	yes
`pagination`	PaginationMeta	yes

RetentionActivationResultDto

Property	Type	Required	Description
`assignmentId`	string (uuid)	yes
`pointerRevision`	string	yes	Serialized `BigInt`. Pass the PREVIOUS value as `expectedPointerRevision` on the next activation — the compare-and-set is what makes two concurrent activations produce one winner and one 409.
`policyWatermark`	string	yes	Serialized `BigInt`. Monotonic across BOTH policy families, so a resolver can tell whether any policy has moved since it last resolved.
`targetKey`	string	yes	The activation pointer key: family + organization + scope + source.

RetentionActivationResultDtoDataEnvelope

Property	Type	Required	Description
`data`	RetentionActivationResultDto	yes

RetentionBundleRefDto

Property	Type	Required	Description
`policyKey`	string	yes
`revision`	number	yes

RetentionDecisionScopeSegmentDto

Property	Type	Required	Description
`id`	string	yes
`kind`	one of `"project"`, `"user"`, `"application"`	yes

RetentionProvenanceDto

Property	Type	Required
`ceiling`	RetentionProvenanceEntryDto or null	yes
`choice`	RetentionProvenanceEntryDto or null	yes
`considered`	array of RetentionProvenanceEntryDto	yes
`floor`	RetentionProvenanceEntryDto or null	yes

RetentionProvenanceEntryDto

Property	Type	Required	Description
`assignmentId`	string (uuid)	yes
`assignmentKey`	string	yes
`assignmentRevision`	number	yes
`bundleId`	string (uuid)	yes
`bundleKey`	string	yes
`bundleRevision`	number	yes
`orgId`	string or null	yes
`pointerRevision`	string	yes	Serialized `BigInt` — the activation pointer this rule was read through.
`role`	one of `"floor"`, `"ceiling"`, `"choice"`	yes
`ruleId`	string	yes
`scopeKind`	one of `"installation"`, `"org"`, `"project"`, `"user"`, `"application"`	yes
`scopeRef`	string	yes
`sourceKind`	one of `"installation_safety"`, `"distribution"`, `"license"`, `"external_entitlement"`, `"platform_org_override"`, `"org_delegated_limit"`	yes
`sourceRef`	string	yes
`windowDays`	number	yes

UsageItemDto

Property	Type	Required	Description
`correctsSourceEventId`	object or null	no
`definitionId`	string	yes
`definitionKey`	string	yes
`definitionRevision`	number	yes
`dimensionsJson`	object	yes
`id`	string	yes
`ingestedAt`	string (date-time)	yes
`intervalEnd`	string (date-time)	yes
`intervalStart`	string (date-time)	yes
`kind`	one of `"usage"`, `"correction"`	yes
`orgId`	string	yes
`producedAt`	string (date-time)	yes
`producerId`	string	yes
`quantityValue`	string	yes	Canonical signed exact decimal string.
`reason`	object or null	no
`sourceEventId`	string	yes
`sourceResourceRef`	object or null	no
`unit`	string	yes

UsageItemDtoPaginatedEnvelope

Property	Type	Required	Description
`data`	array of UsageItemDto	yes
`pagination`	PaginationMeta	yes