Skip to content

Validator: migrate advisory baseline from file-based to annotation-based #729

@arjunmehta-git

Description

@arjunmehta-git

Context

The advisory baseline file (`build/validate-schemas.advisory-baseline.txt`) suppresses known issues by matching exact `file\tmessage` strings.

Problem

  • Fragile: any message wording change invalidates the baseline entry
  • Opaque: the exemption lives in a separate file, not with the schema
  • Hard to audit: reviewers must cross-reference the baseline file to understand why a warning is suppressed

Proposal

Replace with per-schema/per-operation annotations:

```yaml

Exempt from Rule 28 (response code semantics) — intentional 200 for upsert

x-advisory-exempt: [28]
```

The validator would check for `x-advisory-exempt` on the operation or schema and skip the listed rule numbers.

Benefits:

  • Self-documenting — the exemption lives with the schema
  • Survives message rewording
  • Easy to audit in code review

Impact

  • Validator change: add `x-advisory-exempt` support, remove baseline file loading
  • Schema changes: add annotations to constructs currently in the baseline file (currently 8 entries across 4 constructs)
  • Delete `build/validate-schemas.advisory-baseline.txt`

References

Identified in schema validator audit — Section 3e (Advisory Baseline File).

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions