An autofix policy supplies your own values for supported missing metadata. Use it when you already know the description, contact, license or operation ID you want.

A policy does not apply changes on its own. It supplies proposals for the same review and verification flow.

Supply a value

Save this as fix-policy.yaml beside api.yaml:

version: 1
policies:
  - id: api-description
    rule: info-description
    diagnostic: description-missing
    scope:
      source: ./api.yaml
      pointer: /info
    value: Manage orders and track deliveries.

Then preview it:

vacuum lint api.yaml --fix --dry-run --fix-policy fix-policy.yaml

The rule must be enabled in your ruleset. A policy does not turn rules on. The pointer names the object that needs the field: /info, not /info/description.

Field Meaning
version Policy format version. Use 1.
id A unique name for this entry
rule The built-in metadata rule to supply a value for
diagnostic The missing field: description-missing, summary-missing, contact-missing, license-missing or operationId-missing, as supported by the rule
scope.source An exact local source file
scope.pointer An exact JSON Pointer to the object needing the field
value The proposed value, or use catalog for operation text

Descriptions, summaries and operation IDs take strings. Contact values take an object with supported name, email and url fields. License values take an object with supported name, url and identifier fields. Values must fit the field and document version.

Policies fill missing fields. They do not replace fields that already exist, including empty or null values.

Reuse operation text

A catalog maps a source file and unique operation ID to a string. For example, operation-descriptions.yaml:

api.yaml:
  listOrders: List orders visible to the authenticated caller.

Use catalog instead of value in the policy:

version: 1
policies:
  - id: list-orders-description
    rule: operation-description
    diagnostic: description-missing
    scope:
      source: ./api.yaml
      pointer: /paths/~1orders/get
    catalog: ./operation-descriptions.yaml

This entry supplies the description for GET /orders when its operationId is listOrders. In a JSON Pointer, / inside a key is written as ~1. The path key /orders becomes ~1orders.