TenantAtlas/specs/112-list-expand-parity/data-model.md

Data Model — Graph Contracts: LIST $expand Parity Fix

Summary

No database schema changes. This feature changes how list queries are constructed and sanitized for Microsoft Graph.

Key entities & shapes

Graph contract (config/graph_contracts.php)

Per policyType contract keys relevant to this feature:

• resource (string): Graph resource path (e.g. directory/roleAssignments)
• allowed_select (string[]): allowlisted $select fields
• allowed_expand (string[]): allowlisted $expand expansions (exact-match)

Query options (caller input)

Options are passed as an array $options into GraphClientInterface::listPolicies($policyType, $options). Relevant keys:

• select (string|string[]): optional $select input
• expand (string|string[]): optional $expand input
• filter (string): optional $filter
• top (int): optional $top
• platform (string): optional platform filter for contract-specific endpoints
• plus tenant/auth context from MicrosoftGraphOptionsResolver

Sanitized query (outbound)

GraphContractRegistry::sanitizeQuery($policyType, $query) returns:

• query (array): sanitized query map, where $select and $expand are sent as comma-separated strings
• warnings (string[]): human-readable warnings for capability safety

Entra role assignment record

entraRoleAssignments list response item is expected to include:

• roleDefinitionId (string)
• principalId (string)
• principal (object, when expanded)
  • displayName (string)
  • @odata.type (string)

State transitions

None. This is a read-only integration-layer capability change.

Validation rules

• $expand values must match allowed_expand exactly.
• $expand normalization: trim, split on top-level commas only (string input; do not split inside balanced parentheses), drop empty, dedupe.
• Safety caps: max 10 allowed expands; max 200 chars per token.