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

name

string

Yes

Role name, 1–255 UTF-8 bytes, without whitespace or control characters. System-reserved names are invalid.

description

string

No

Role description, at most 4096 UTF-8 bytes, without NUL. Omission/null saves an empty string.

schema_version

string

Yes

schema_version returned by permission definitions.

request_id

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.

expected_lifecycle_version

integer

Yes

Expected role lifecycle version; must be greater than 0.

expected_policy_version

integer

Yes

Expected application policy version; at least 1.

expected_data_privilege_version

integer

No

Expected data privilege version; at least 0.

statements

object (array of objects) or null

No

Application policy statements.

statements[].statement_id

string

No

Unique IAM policy statement identifier.

statements[].action_id

string

When the object is supplied

Permission action.

statements[].resource_type

string

When the object is supplied

Resource type.

statements[].scope_mode

string

When the object is supplied

Resource scope: all or resources.

statements[].resource_id

string

No

Resource ID.

statements[].condition_hash

string

No

Condition summary.

statements[].target_action_id

string

No

Granted actions.

statements[].grant_scope_mode

string

No

Delegation scope: all, resources, or an empty string.

statements[].grant_resource_id

string

No

Delegation target resource IDs according to the current permission definition and scope.

statements[].grant_delegatable

boolean

No

Whether application permissions may be delegated further.

data_privilege_mutations

object (array of objects) or null

No

Incremental data privilege changes.

data_privilege_mutations[].operation

string

When the object is supplied

Operation: grant or revoke.

data_privilege_mutations[].action_id

string

When the object is supplied

Permission action.

data_privilege_mutations[].resource_type

string

When the object is supplied

Resource type: database or table.

data_privilege_mutations[].resource_id

string

When the object is supplied

Resource ID.

data_privilege_mutations[].privilege

string

When the object is supplied

MatrixOne privilege: create_table, select, insert, update, or delete.

data_privilege_mutations[].with_grant_option

boolean

No

Whether granting also permits the target role to delegate that data privilege. Default false.

data_privilege_mutations[].row_column

object or null

For a table SELECT grant

Handling of row/column rules for the target role. Retaining existing rules also requires mode=keep.

data_privilege_mutations[].row_column.mode

string

When row_column is supplied

Mode: keep, set, or clear.

data_privilege_mutations[].row_column.draft

object

When mode=set

Draft row/column rules.

data_privilege_mutations[].row_column.draft.black_column_list

string (array of strings) or null

No

Columns denied access.

data_privilege_mutations[].row_column.draft.rule_list

object (array of objects) or null

No

Row filter rules.

data_privilege_mutations[].row_column.draft.rule_list[].column

string

No

Column name.

data_privilege_mutations[].row_column.draft.rule_list[].relation

string

No

Condition conjunction: and or or.

data_privilege_mutations[].row_column.draft.rule_list[].expression_list

object (array of objects) or null

No

SQL expression rule.

data_privilege_mutations[].row_column.draft.rule_list[].expression_list[].operator

string

No

Comparison operator: =, !=, >, >=, <, <=, like, regexp_like, in, not in, or expression.

data_privilege_mutations[].row_column.draft.rule_list[].expression_list[].expression

string (array of strings) or null

No

Condition values.

data_privilege_mutations[].row_column.draft.rule_list[].expression_list[].match_type

string

No

Value matching type: empty string, c, i, m, n, or u.

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.

Last updated on