ahmido
8ee1174c8d
## Summary - add the shared resolved-reference foundation with registry, resolvers, presenters, and badge semantics - refactor related context, assignment evidence, and policy-version assignment rendering toward label-first reference presentation - add Spec 132 artifacts and focused Pest coverage for reference resolution, degraded states, canonical linking, and tenant-context carryover ## Verification - `vendor/bin/sail bin pint --dirty --format agent` - focused Pest verification was marked complete in the task artifact ## Notes - this PR is opened from the current session branch - `specs/132-guid-context-resolver/tasks.md` reflects in-progress completion state for the implemented tasks Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #161
248 lines
6.0 KiB
YAML
248 lines
6.0 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Reference Presentation Contract
|
|
version: 0.1.0
|
|
description: >-
|
|
Internal contract for the shared reference-resolution and presentation layer used by
|
|
existing Filament resources, infolists, related-context sections, and dense list surfaces.
|
|
This feature introduces no new public HTTP API; the contract formalizes the payloads,
|
|
states, and canonical-link rules required for label-first reference rendering.
|
|
paths: {}
|
|
components:
|
|
schemas:
|
|
ReferenceDescriptor:
|
|
type: object
|
|
required:
|
|
- referenceClass
|
|
- rawIdentifier
|
|
properties:
|
|
referenceClass:
|
|
type: string
|
|
enum:
|
|
- policy
|
|
- policy_version
|
|
- baseline_profile
|
|
- baseline_snapshot
|
|
- operation_run
|
|
- backup_set
|
|
- role_definition
|
|
- principal
|
|
- group
|
|
- service_principal
|
|
- tenant_external_object
|
|
- unsupported
|
|
rawIdentifier:
|
|
type: string
|
|
example: 8df3de3c-6287-44a4-b303-5d6d0a3d1c55
|
|
workspaceId:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
tenantId:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
sourceType:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: finding
|
|
sourceSurface:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
enum:
|
|
- detail_section
|
|
- detail_header
|
|
- list_row
|
|
- assignment_block
|
|
fallbackLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Global Administrator
|
|
linkedModelType:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: App\Models\PolicyVersion
|
|
linkedModelId:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
context:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
ResolvedReference:
|
|
type: object
|
|
required:
|
|
- referenceClass
|
|
- rawIdentifier
|
|
- primaryLabel
|
|
- state
|
|
- technicalDetail
|
|
properties:
|
|
referenceClass:
|
|
type: string
|
|
example: policy_version
|
|
rawIdentifier:
|
|
type: string
|
|
example: pv_1829
|
|
primaryLabel:
|
|
type: string
|
|
example: Windows Security Baseline v12
|
|
secondaryLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Policy version
|
|
state:
|
|
type: string
|
|
enum:
|
|
- resolved
|
|
- partially_resolved
|
|
- unresolved
|
|
- deleted_or_missing
|
|
- inaccessible
|
|
- external_limited_context
|
|
stateLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Partially resolved
|
|
linkTarget:
|
|
$ref: '#/components/schemas/ReferenceLinkTarget'
|
|
technicalDetail:
|
|
$ref: '#/components/schemas/ReferenceTechnicalDetail'
|
|
meta:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
ReferenceLinkTarget:
|
|
type:
|
|
- object
|
|
- 'null'
|
|
required:
|
|
- targetKind
|
|
- url
|
|
- actionLabel
|
|
properties:
|
|
targetKind:
|
|
type: string
|
|
example: operation_run
|
|
url:
|
|
type: string
|
|
format: uri-reference
|
|
example: /admin/operations/482
|
|
actionLabel:
|
|
type: string
|
|
example: View run
|
|
contextBadge:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Tenant context
|
|
|
|
ReferenceTechnicalDetail:
|
|
type: object
|
|
required:
|
|
- fullId
|
|
- copyable
|
|
- defaultCollapsed
|
|
properties:
|
|
displayId:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: …0a3d1c55
|
|
fullId:
|
|
type: string
|
|
example: 8df3de3c-6287-44a4-b303-5d6d0a3d1c55
|
|
sourceHint:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Captured from baseline evidence
|
|
copyable:
|
|
type: boolean
|
|
default: true
|
|
defaultCollapsed:
|
|
type: boolean
|
|
default: true
|
|
|
|
ReferencePresentationBlock:
|
|
type: object
|
|
required:
|
|
- variant
|
|
- references
|
|
properties:
|
|
variant:
|
|
type: string
|
|
enum:
|
|
- compact
|
|
- detail
|
|
title:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: Related context
|
|
references:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ResolvedReference'
|
|
emptyMessage:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example: No related context is available for this record.
|
|
|
|
ReferenceResolverRegistration:
|
|
type: object
|
|
required:
|
|
- referenceClass
|
|
- resolver
|
|
- supportsLinking
|
|
- supportsPartialResolution
|
|
properties:
|
|
referenceClass:
|
|
type: string
|
|
example: group
|
|
resolver:
|
|
type: string
|
|
example: EntraGroupReferenceResolver
|
|
supportsLinking:
|
|
type: boolean
|
|
supportsPartialResolution:
|
|
type: boolean
|
|
supportedSurfaces:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- detail_section
|
|
- detail_header
|
|
- list_row
|
|
- assignment_block
|
|
|
|
ReferenceDegradedState:
|
|
type: object
|
|
required:
|
|
- state
|
|
- operatorMessage
|
|
- retainTechnicalDetail
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum:
|
|
- unresolved
|
|
- deleted_or_missing
|
|
- inaccessible
|
|
- external_limited_context
|
|
- partially_resolved
|
|
operatorMessage:
|
|
type: string
|
|
example: This group reference is no longer available in the current tenant context.
|
|
retainTechnicalDetail:
|
|
type: boolean
|
|
default: true |