# Schema Governance for Scanner Outputs (SC9)

Status: Draft · Date: 2025-12-04
Scope: Define governance, approvals, RACI, and review cadence for schema bumps, downgrade adapters, and mapping table changes.

## Objectives

- Establish clear ownership and approval workflows for schema changes.
- Define RACI matrix for schema-related decisions.
- Set review cadence and change control procedures.
- Ensure adapter tables are locked with documented changes.

## RACI Matrix

### Schema Changes

| Activity | Product | Scanner TL | Sbomer TL | Policy TL | Ops | QA |
|----------|---------|------------|-----------|-----------|-----|-----|
| CycloneDX version bump | A | R | C | C | I | C |
| CVSS version support | A | R | I | C | I | C |
| SLSA version bump | A | R | C | C | I | C |
| New evidence fields | A | R | C | C | I | C |
| CBOM property additions | A | R | C | C | I | C |

### Adapter Changes

| Activity | Product | Scanner TL | Sbomer TL | Policy TL | Ops | QA |
|----------|---------|------------|-----------|-----------|-----|-----|
| Downgrade adapter update | A | R | C | I | I | R |
| Mapping table changes | A | R | C | I | I | R |
| Hash update approval | A | R | I | I | I | R |
| Fixture updates | I | R | C | I | I | R |

### Release Artifacts

| Activity | Product | Scanner TL | Sbomer TL | Policy TL | Ops | QA |
|----------|---------|------------|-----------|-----------|-----|-----|
| Schema freeze | A | R | C | C | I | I |
| DSSE signing | I | C | I | I | R | I |
| Offline kit bundling | I | I | I | I | R | C |
| Release notes | R | C | C | C | C | I |

Legend: R=Responsible, A=Accountable, C=Consulted, I=Informed

## Schema Bump Workflow

### 1. Proposal Phase

```mermaid
graph LR
    A[RFC Draft] --> B[Technical Review]
    B --> C{Approved?}
    C -->|Yes| D[Implementation]
    C -->|No| A
    D --> E[Adapter Update]
    E --> F[Fixture Update]
    F --> G[Hash Freeze]
    G --> H[DSSE Sign]
    H --> I[Release]
```

### 2. Required Artifacts

| Artifact | Owner | Location |
|----------|-------|----------|
| RFC Document | Scanner TL | `docs/rfcs/scanner/` |
| Mapping CSV | Scanner TL | `docs/modules/scanner/fixtures/adapters/` |
| Golden Fixtures | QA | `docs/modules/scanner/fixtures/cdx17-cbom/` |
| Hash List | QA | `docs/modules/scanner/fixtures/*/hashes.txt` |
| DSSE Envelope | Ops | `out/offline/scanner-standards-kit-v1/` |

### 3. Approval Gates

| Gate | Approvers | Criteria |
|------|-----------|----------|
| RFC Approval | Product + Scanner TL | Technical feasibility, backwards compat |
| Adapter Approval | Scanner TL + QA | Mapping completeness, determinism tests pass |
| Hash Freeze | Scanner TL + QA | All fixtures pass hash validation |
| DSSE Sign | Ops | All hashes recorded, offline kit complete |
| Release | Product | All gates passed, release notes approved |

## Review Cadence

### Regular Reviews

| Review | Frequency | Attendees | Scope |
|--------|-----------|-----------|-------|
| Schema Sync | Monthly | Scanner, Sbomer, Policy TLs | Upcoming changes, deprecations |
| Adapter Review | Per release | Scanner TL, QA | Mapping accuracy, test coverage |
| Hash Audit | Per release | QA, Ops | All fixture hashes valid |

### Ad-hoc Reviews

Triggered by:
- Upstream schema release (CycloneDX, SPDX, SLSA)
- Security advisory requiring field changes
- Customer request for new evidence types
- Determinism test failure

## Change Control

### Acceptable Changes

| Change Type | Requires | Example |
|-------------|----------|---------|
| Add optional field | Scanner TL approval | New evidence property |
| Add required field | RFC + Product approval | New mandatory hash |
| Remove field | RFC + deprecation notice | Legacy property removal |
| Change ordering | Scanner TL + QA approval | Sort key update |
| Update hash | QA approval + documented reason | Fixture content change |

### Prohibited Changes

| Change | Reason | Alternative |
|--------|--------|-------------|
| Silent hash update | Breaks determinism validation | Document change, get approval |
| Remove required field | Breaks consumers | Deprecate with N-1 support |
| Change field type | Breaks serialization | New field with migration |
| Reorder without docs | Breaks hash validation | Update ordering rules + hashes |

## Deprecation Policy

### Deprecation Timeline

| Phase | Duration | Actions |
|-------|----------|---------|
| Announced | +0 days | Add deprecation notice to docs |
| Warning | +30 days | Emit warning in API responses |
| N-1 Support | +90 days | Old format still accepted |
| Removal | +180 days | Old format rejected |

### Deprecation Notice Format

```json
{
  "deprecated": {
    "field": "ratings[method=CVSSv30]",
    "since": "v2.5.0",
    "removal": "v3.0.0",
    "replacement": "ratings[method=CVSSv31]",
    "migrationGuide": "docs/migrations/cvss-v30-removal.md"
  }
}
```

## Adapter Locking

### Lock Conditions

Adapters are locked when:
1. Hash recorded in `hashes.txt`
2. DSSE envelope signed
3. Offline kit bundled

### Unlock Process

To modify a locked adapter:
1. Create new version (e.g., `mapping-cvss4-to-cvss3-v2.csv`)
2. Update hash file with new entry
3. Keep old version for N-1 compatibility
4. Get Scanner TL + QA approval
5. Sign new DSSE envelope

## Audit Trail

### Required Records

| Record | Location | Retention |
|--------|----------|-----------|
| RFC decisions | `docs/rfcs/scanner/` | Permanent |
| Hash changes | Git history + `CHANGELOG.md` | Permanent |
| Approval records | PR comments | Permanent |
| DSSE envelopes | CAS + offline kit | Permanent |

### Git Commit Requirements

Schema-related commits must include:
```
feat(scanner): Add CVSS v4 support

- Add CVSSv4 rating method
- Update adapter mapping CSV
- Update golden fixtures
- New hashes recorded

Approved-By: @scanner-tl
Reviewed-By: @qa-lead
Hash-Update: mapping-cvss4-to-cvss3.csv BLAKE3=fa600b26...

Refs: RFC-2025-012, SCAN-GAP-186-SC9
```

## Links

- Sprint: `docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md` (SC9)
- Roadmap: `docs/modules/scanner/design/standards-convergence-roadmap.md` (SC1)
- Adapters: `docs/modules/scanner/fixtures/adapters/`