44 lines
1.9 KiB
Markdown
44 lines
1.9 KiB
Markdown
# 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.
|