openapi: 3.1.0
info:
  title: Cross-Resource Navigation Presentation Contract
  version: 0.1.0
  description: >-
    Internal contract for the shared related-navigation presentation layer used by
    existing Filament pages and resources. This feature introduces no new public HTTP API;
    the contract formalizes the payloads and rules that drive related-context sections,
    drill-down actions, canonical route selection, and unavailable-state rendering.
paths: {}
components:
  schemas:
    NavigationMatrixRule:
      type: object
      required:
        - sourceType
        - sourceSurface
        - relationKey
        - targetType
        - targetMode
        - label
        - priority
        - missingStatePolicy
      properties:
        sourceType:
          type: string
          example: finding
        sourceSurface:
          type: string
          enum:
            - detail_section
            - detail_header
            - list_row
            - canonical_list
        relationKey:
          type: string
          example: source_run
        targetType:
          type: string
          example: operation_run
        targetMode:
          type: string
          enum:
            - direct_record
            - filtered_list
            - canonical_page
        label:
          type: string
          example: View run
        priority:
          type: integer
          minimum: 1
        requiresCapabilityCheck:
          type: boolean
          default: true
        missingStatePolicy:
          type: string
          enum:
            - hide
            - show_unavailable
            - show_reference_only
    RelatedContextSection:
      type: object
      required:
        - title
        - entries
      properties:
        title:
          type: string
          example: Related context
        entries:
          type: array
          items:
            $ref: '#/components/schemas/RelatedContextEntry'
        primaryEntryKey:
          type:
            - string
            - 'null'
        emptyMessage:
          type:
            - string
            - 'null'
    RelatedContextEntry:
      type: object
      required:
        - key
        - label
        - value
        - targetKind
        - availability
      properties:
        key:
          type: string
          example: baseline_profile
        label:
          type: string
          example: Baseline profile
        value:
          type: string
          example: Windows Security Baseline
        secondaryValue:
          type:
            - string
            - 'null'
          example: '#42'
        targetUrl:
          type:
            - string
            - 'null'
          format: uri-reference
        targetKind:
          type: string
          example: baseline_profile
        availability:
          type: string
          enum:
            - available
            - missing
            - unauthorized
            - unresolved
        unavailableReason:
          type:
            - string
            - 'null'
        contextBadge:
          type:
            - string
            - 'null'
          example: Tenant context
    DrillDownAction:
      type: object
      required:
        - label
        - placement
        - priority
        - targetKind
        - visible
      properties:
        label:
          type: string
          example: View snapshot
        url:
          type:
            - string
            - 'null'
          format: uri-reference
        placement:
          type: string
          enum:
            - row_action
            - header_action
            - inline_entry
            - grouped_action
        priority:
          type: integer
          minimum: 1
        targetKind:
          type: string
          example: baseline_snapshot
        visible:
          type: boolean
        disabledReason:
          type:
            - string
            - 'null'
    CanonicalNavigationContext:
      type: object
      required:
        - workspaceId
        - sourceSurface
        - canonicalRouteName
      properties:
        workspaceId:
          type: integer
        tenantId:
          type:
            - integer
            - 'null'
        sourceSurface:
          type: string
          example: finding.detail
        canonicalRouteName:
          type: string
          example: admin.operations.view
        filterPayload:
          type: object
          additionalProperties: true
        backLinkLabel:
          type:
            - string
            - 'null'
          example: Back to Findings
    UnavailableRelationState:
      type: object
      required:
        - relationKey
        - reason
        - message
        - showReference
      properties:
        relationKey:
          type: string
          example: source_policy_version
        referenceValue:
          type:
            - string
            - 'null'
          example: 'pv_1282'
        reason:
          type: string
          enum:
            - missing
            - deleted
            - unauthorized
            - unresolved
        message:
          type: string
          example: Related policy version is no longer available.
        showReference:
          type: boolean