225 lines
6.8 KiB
YAML
225 lines
6.8 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Baseline Summary Surface Contract
|
|
version: 1.0.0
|
|
description: >-
|
|
Internal contract for baseline compare summary semantics across tenant dashboard,
|
|
Baseline Compare landing, findings-adjacent warning surfaces, and canonical run-detail alignment.
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
/admin:
|
|
get:
|
|
summary: Tenant dashboard baseline summary contract
|
|
description: >-
|
|
HTML tenant dashboard surface whose embedded baseline summary semantics must obey the shared summary assessment.
|
|
responses:
|
|
'200':
|
|
description: Dashboard rendered with an embedded baseline summary assessment
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TenantDashboardBaselineSummary'
|
|
/admin/baseline-compare:
|
|
get:
|
|
summary: Baseline Compare landing summary contract
|
|
description: >-
|
|
Landing surface for the latest baseline compare result. The primary summary must not exceed the trust carried by the underlying explanation.
|
|
responses:
|
|
'200':
|
|
description: Landing page rendered with primary summary assessment and diagnostics links
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BaselineLandingSummary'
|
|
/admin/findings:
|
|
get:
|
|
summary: Findings-adjacent baseline warning contract
|
|
description: >-
|
|
Findings context that may display a coverage or evidence caution banner derived from the same summary assessment.
|
|
responses:
|
|
'200':
|
|
description: Findings page rendered with optional baseline summary caution
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BaselineBannerSummary'
|
|
/admin/operations/{run}:
|
|
get:
|
|
summary: Canonical baseline compare run-detail reference contract
|
|
description: >-
|
|
Canonical run detail remains the deepest truth surface. Compact summaries may not be more optimistic than this contract.
|
|
parameters:
|
|
- name: run
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Run detail rendered with baseline compare truth semantics
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/BaselineRunDetailReference'
|
|
components:
|
|
schemas:
|
|
SummaryStateFamily:
|
|
type: string
|
|
enum:
|
|
- positive
|
|
- caution
|
|
- stale
|
|
- action_required
|
|
- unavailable
|
|
- in_progress
|
|
TrustworthinessLevel:
|
|
type: string
|
|
enum:
|
|
- trustworthy
|
|
- limited_confidence
|
|
- diagnostic_only
|
|
- unusable
|
|
EvaluationResult:
|
|
type: string
|
|
description: >-
|
|
`failed_result` represents a compare execution that completed without a usable decision-grade artifact
|
|
and therefore must map to an investigation-oriented `action_required` summary state rather than
|
|
`unavailable`.
|
|
enum:
|
|
- full_result
|
|
- no_result
|
|
- incomplete_result
|
|
- failed_result
|
|
- suppressed_result
|
|
- unavailable
|
|
EvidenceImpact:
|
|
type: string
|
|
enum:
|
|
- none
|
|
- coverage_warning
|
|
- evidence_gap
|
|
- stale_result
|
|
- suppressed_output
|
|
- unavailable
|
|
NextAction:
|
|
type: object
|
|
required:
|
|
- label
|
|
- target
|
|
properties:
|
|
label:
|
|
type: string
|
|
target:
|
|
type: string
|
|
enum:
|
|
- landing
|
|
- findings
|
|
- run
|
|
- none
|
|
BaselineSummaryAssessment:
|
|
type: object
|
|
description: >-
|
|
Shared compact-summary contract. If `evaluationResult` is `failed_result`, `stateFamily` must be
|
|
`action_required` and `nextAction.target` must not be `none`.
|
|
required:
|
|
- stateFamily
|
|
- headline
|
|
- positiveClaimAllowed
|
|
- trustworthinessLevel
|
|
- evaluationResult
|
|
- evidenceImpact
|
|
- nextAction
|
|
properties:
|
|
stateFamily:
|
|
$ref: '#/components/schemas/SummaryStateFamily'
|
|
headline:
|
|
type: string
|
|
supportingMessage:
|
|
type: string
|
|
nullable: true
|
|
tone:
|
|
type: string
|
|
positiveClaimAllowed:
|
|
type: boolean
|
|
trustworthinessLevel:
|
|
$ref: '#/components/schemas/TrustworthinessLevel'
|
|
evaluationResult:
|
|
$ref: '#/components/schemas/EvaluationResult'
|
|
evidenceImpact:
|
|
$ref: '#/components/schemas/EvidenceImpact'
|
|
findingsVisibleCount:
|
|
type: integer
|
|
minimum: 0
|
|
highSeverityCount:
|
|
type: integer
|
|
minimum: 0
|
|
reasonCode:
|
|
type: string
|
|
nullable: true
|
|
lastComparedLabel:
|
|
type: string
|
|
nullable: true
|
|
nextAction:
|
|
$ref: '#/components/schemas/NextAction'
|
|
TenantDashboardBaselineSummary:
|
|
type: object
|
|
required:
|
|
- widget
|
|
- needsAttention
|
|
properties:
|
|
widget:
|
|
$ref: '#/components/schemas/BaselineSummaryAssessment'
|
|
needsAttention:
|
|
$ref: '#/components/schemas/BaselineSummaryAssessment'
|
|
kpiCards:
|
|
type: array
|
|
description: Quantitative indicators only; not claim-bearing semantics.
|
|
items:
|
|
type: object
|
|
required:
|
|
- label
|
|
- value
|
|
properties:
|
|
label:
|
|
type: string
|
|
value:
|
|
type: integer
|
|
minimum: 0
|
|
BaselineLandingSummary:
|
|
type: object
|
|
required:
|
|
- primarySummary
|
|
properties:
|
|
primarySummary:
|
|
$ref: '#/components/schemas/BaselineSummaryAssessment'
|
|
diagnosticsAvailable:
|
|
type: boolean
|
|
runLinkAvailable:
|
|
type: boolean
|
|
findingsLinkAvailable:
|
|
type: boolean
|
|
BaselineBannerSummary:
|
|
type: object
|
|
required:
|
|
- shouldShow
|
|
properties:
|
|
shouldShow:
|
|
type: boolean
|
|
bannerSummary:
|
|
allOf:
|
|
- $ref: '#/components/schemas/BaselineSummaryAssessment'
|
|
nullable: true
|
|
BaselineRunDetailReference:
|
|
type: object
|
|
required:
|
|
- primarySummary
|
|
properties:
|
|
primarySummary:
|
|
$ref: '#/components/schemas/BaselineSummaryAssessment'
|
|
semanticCeiling:
|
|
type: boolean
|
|
description: Always true for the canonical detail; compact surfaces may not exceed this confidence.
|
|
x-tenantpilot-notes:
|
|
- These routes render HTML in practice; the schema models the internal summary payload that their views must honor.
|
|
- No new HTTP endpoints are introduced by this feature. |