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