UpdateReferenceList parity mapping

Supported in:

This guide details the request and response mapping specifications and property parity analysis for migrating from the legacy Backstory Reference List API (UpdateReferenceList) to the modern Chronicle API (UpdateReferenceList).

Protocol and mapping overview

Feature Legacy API (UpdateReferenceList) Modern Chronicle API (UpdateReferenceList)
HTTP Method PATCH PATCH
Permissions Partner token or legacy API keys chronicle.googleapis.com/referenceLists.update

Request payload field-by-field parity

The modern Chronicle API UpdateReferenceListRequest scopes updates using canonical Google Cloud resource paths and renames payload attributes.

Legacy Field (UpdateReferenceListRequest / ReferenceList) Modern Field (UpdateReferenceListRequest / ReferenceList) Field type Parity & Migration Notes
list.name reference_list.name (in HTTP path) string Google Cloud Scoping Context / Renaming: The legacy request used path format lists/{list} under list.name. The modern API routes this using canonical Google Cloud resource paths under reference_list.name: projects/{project}/locations/{location}/instances/{instance}/referenceLists/{reference_list}.
list reference_list ReferenceList Parity Mapped / Renamed: The payload containing reference list properties. Rename from list to referenceList in JSON requests.
update_mask update_mask FieldMask Parity Mapped / Behavior Note: Standard FieldMask selecting updated properties. When no mask is supplied, all non-empty fields will be updated. A mask of * updates all fields, whether empty or not. Rename to updateMask in JSON.

Nested ReferenceList payload fields mapped

The fields mapping inside the ReferenceList request is as follows:

Legacy Field (ReferenceList request) Modern Field (ReferenceList request) Field type Parity & Migration Notes
name name string Contains canonical Google Cloud resource path identifying the list to update.
description description string Parity Mapped: User-provided description text.
lines entries repeated string $\rightarrow$ repeated ReferenceListEntry Restructured: Legacy flat array of string lines is restructured into a repeated list of ReferenceListEntry messages (entries[].value).
content_type syntax_type enum Renamed / Value Alignment: Renamed from content_type to syntax_type. Enum mappings:
• CONTENT_TYPE_DEFAULT_STRING $\rightarrow$ REFERENCE_LIST_SYNTAX_TYPE_PLAIN_TEXT_STRING
• REGEX $\rightarrow$ REFERENCE_LIST_SYNTAX_TYPE_REGEX (for regular expressions)
• CIDR $\rightarrow$ REFERENCE_LIST_SYNTAX_TYPE_CIDR. Rename to syntaxType in JSON.
— scope_info ScopeInfo New Field: Specifies Data RBAC access scopes (scope_info.reference_list_scope.scope_names). If requested to be updated, this field must be set. Rename to scopeInfo in JSON.
create_time revision_create_time Timestamp Ignored / Output-Only: Populated post-update by backend storage engines.

Response payload field-by-field parity

Both responses return the updated reference list representation, with the modern API enriching return payloads with rule associations and RBAC scopes.

Legacy Field (ReferenceList response) Modern Field (ReferenceList response) Field type Parity & Migration Notes
name name string Parity Mapped: Contains standard Google Cloud canonical resource path: projects/{pr}/locations/{loc}/instances/{in}/referenceLists/{id}.
— display_name string New Field: The unique display title of the reference list. Rename to displayName in JSON responses.
description description string User-provided description text.
lines entries repeated ReferenceListEntry Restructured: Each item is returned as a ReferenceListEntry message containing string value = 1;.
content_type syntax_type enum Renamed: Returns ReferenceListSyntaxType enum representing list validation rules (PLAIN_TEXT_STRING, REGEX, CIDR). Rename to syntaxType in JSON.
create_time revision_create_time Timestamp Renamed: Timestamp recording when the updated revision was created. Rename to revisionCreateTime in JSON.
— rules repeated string New Field: Array of self-authored detection rule names associating with this list.
— rule_associations_count int32 New Field: Total count of active self-authored rules referencing this list. Rename to ruleAssociationsCount in JSON.
— scope_info ScopeInfo New Field: Data RBAC scoping boundaries assigned to the list. Rename to scopeInfo in JSON.

Key differences

  • Google Cloud Project Scoping and Field Renaming:
    • Scoped natively under parent project instance folder bindings (reference_list.name path parameter).
    • Notice that on the request message, the payload field is renamed from list to reference_list.
  • Payload Restructuring:
    • Plain string line arrays in legacy lines are wrapped inside structured ReferenceListEntry messages under entries (for example, repeated string $\rightarrow$ repeated ReferenceListEntry).
  • Syntax Type and Field Renaming:
    • Legacy content_type is renamed to syntax_type with clearer enum prefixing (REFERENCE_LIST_SYNTAX_TYPE_*). Legacy create_time is renamed to revision_create_time.
  • Rule Tracking and Scoping Enrichment:
    • The modern response enriches return payloads with RBAC scoping (scope_info) and rule association analytics (rules array and rule_associations_count).