CreateReferenceList 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 (CreateReferenceList) to the modern Chronicle API (CreateReferenceList).

Protocol and mapping overview

Feature Legacy API (CreateReferenceList) Modern Chronicle API (CreateReferenceList)
HTTP Method POST POST
Permissions Partner token or legacy API keys chronicle.googleapis.com/referenceLists.create

Request payload field-by-field parity

The modern Chronicle API CreateReferenceListRequest scopes creation under a target parent instance and requires an explicit reference list identifier.

Legacy Field (CreateReferenceListRequest / ReferenceList) Modern Field (CreateReferenceListRequest / ReferenceList) Field type Parity & Migration Notes
— parent (in HTTP path) string Google Cloud Scoping Context: Scopes creation under target parent instances: projects/{project}/locations/{location}/instances/{instance_uuid}.
list.name reference_list_id string Architectural Shift / Explicit ID: Legacy extracted the list identifier from list.name (lists/{list}). The modern Chronicle API request requires reference_list_id as an explicit required request parameter. Rename to referenceListId in JSON.
list reference_list ReferenceList Parity Mapped / Renamed: The payload containing reference list properties. Rename from list to referenceList in JSON requests.

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 Ignored / Output-Only: Generated by the backend in canonical form: projects/{pr}/locations/{loc}/instances/{in}/referenceLists/{id}.
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). Rename to scopeInfo in JSON.
create_time revision_create_time Timestamp Ignored / Output-Only: Populated post-creation by backend storage engines.

Response payload field-by-field parity

Both responses return the created 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 (matching reference_list_id). Rename to displayName in JSON responses.
description description string User-provided description.
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 responses.
create_time revision_create_time Timestamp Renamed: Timestamp recording when the 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 Explicit IDs:
    • Scoped natively under parent project instance folder bindings.
    • Creation requests require an explicit reference_list_id string rather than parsing IDs out of nested list.name paths.
  • 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).