Shared role write requests and results¶
Creation and update share a request shape, but differ in required fields, initial permissions, request IDs, and post-failure confirmation. The tables are not interchangeable wholesale.
Request fields¶
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Role name, 1–255 UTF-8 bytes, without whitespace or control characters. System-reserved names are invalid. |
|
string |
No |
Role description, at most 4096 UTF-8 bytes, without NUL. Omission/null saves an empty string. |
|
string |
Yes |
schema_version returned by permission definitions. |
|
string |
No |
Business request ID for this save, at most 64 UTF-8 bytes, without whitespace or control characters. Generated by the server when omitted. |
|
integer |
Yes |
Expected role lifecycle version; must be greater than 0. |
|
integer |
Yes |
Expected application policy version; at least 1. |
|
integer |
No |
Expected data privilege version; at least 0. |
|
object (array of objects) or null |
No |
Application policy statements. |
|
string |
No |
Unique IAM policy statement identifier. |
|
string |
When the object is supplied |
Permission action. |
|
string |
When the object is supplied |
Resource type. |
|
string |
When the object is supplied |
Resource scope: |
|
string |
No |
Resource ID. |
|
string |
No |
Condition summary. |
|
string |
No |
Granted actions. |
|
string |
No |
Delegation scope: |
|
string |
No |
Delegation target resource IDs according to the current permission definition and scope. |
|
boolean |
No |
Whether application permissions may be delegated further. |
|
object (array of objects) or null |
No |
Incremental data privilege changes. |
|
string |
When the object is supplied |
Operation: |
|
string |
When the object is supplied |
Permission action. |
|
string |
When the object is supplied |
Resource type: |
|
string |
When the object is supplied |
Resource ID. |
|
string |
When the object is supplied |
MatrixOne privilege: |
|
boolean |
No |
Whether granting also permits the target role to delegate that data privilege. Default false. |
|
object or null |
For a table SELECT grant |
Handling of row/column rules for the target role. Retaining existing rules also requires mode=keep. |
|
string |
When row_column is supplied |
Mode: |
|
object |
When mode=set |
Draft row/column rules. |
|
string (array of strings) or null |
No |
Columns denied access. |
|
object (array of objects) or null |
No |
Row filter rules. |
|
string |
No |
Column name. |
|
string |
No |
Condition conjunction: |
|
object (array of objects) or null |
No |
SQL expression rule. |
|
string |
No |
Comparison operator: |
|
string (array of strings) or null |
No |
Condition values. |
|
string |
No |
Value matching type: empty string, |
statements is a complete replacement. Omission, null, and [] all submit an empty custom policy rather than retaining the original array. The server handles mandatory system baseline permissions. data_privilege_mutations is incremental; omission, null, and [] add no data privilege changes. Even a description-only update must include the complete application policy to retain.
Granting SELECT on a table requires row_column; use {"mode":"keep"} to retain current rules. Revocation permits omission or clear. Other data privileges do not accept row/column rules. Actual set/clear operations also require support in the current permission definition.
Creation and update differences¶
Creation does not submit the three existing-role versions. It requires a business request_id and at least one effective initial permission. Updates use all three actual versions for concurrency protection and allow omitting request_id. They replace custom application policies completely and handle data privileges incrementally. The server still manages required system baselines.
Creation succeeds with 201 and update with 200. Success objects contain role_id, role_version, policy_version, data_privilege_version, session_invalidation_status, idempotent_replay, provisioning_state/version/error_code, and request/trace identifiers. Only ready represents successful submission here. Internal pending/failed states are not success.
Failure outcomes and specification conflicts¶
ErrIAMRoleWriteRolledBack, ErrIAMRoleWriteFailed, and ErrIAMRoleWriteResultUnknown distinguish local rollback, stopped cross-MatrixOne operations, and unknown outcomes. Older business catalog text says failed edits restore old snapshots. Lifecycle 04, public contract 07, and the current role_update owner distinguish local rollback from stopping cross-database work without reversing permissions. A promise that every failure restores old permissions is invalid. Specification drift remains separately recorded for internal confirmation, without changing product specifications or implementation.
For unknown creation outcomes, retain the original business identifier and content for confirmation. An update without an identifier is a new save: retain the draft, refresh actual state, and let the user explicitly save again. Do not impose creation-form locking on every setting. Only the corresponding confirmed-rollback error may supply cause_code. Failed/unknown outcomes cannot be inferred as ineffective from underlying error chains.