vocabulary: locations, areas, kinds, statuses, and categories

Every field the model uses is now defined in its vocabulary: the
location grammar and claim syntax, the areas and kinds carried by each
change, and the statuses and categories carried by each coverage row.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QDvUFsg5nu1NBWQffErGDw

Author: reuvenharrison

generator/main.go

@@ -31,11 +31,20 @@ type Model struct {
 }
 
 type Vocabulary struct {
+	// Locations describes the location grammar and the claim syntax built
+	// on it; locations are an open set derived from the OpenAPI object
+	// model, not an enumeration.
+	Locations  string            `yaml:"locations"`
 	Actions    map[string]string `yaml:"actions"`
 	Directions map[string]string `yaml:"directions"`
+	Areas      map[string]string `yaml:"areas"`
+	Kinds      map[string]string `yaml:"kinds"`
 	Effects    map[string]string `yaml:"effects"`
 	Guards     map[string]string `yaml:"guards"`
 	Levels     map[string]string `yaml:"levels"`
+	// Statuses and Categories describe the coverage dispositions.
+	Statuses   map[string]string `yaml:"statuses"`
+	Categories map[string]string `yaml:"categories"`
 }
 
 type SeverityLaw struct {
@@ -112,6 +121,11 @@ func main() {
 		Version:       "0.1.0-draft",
 		GeneratedFrom: "oasdiff " + oasdiffVersion(),
 		Vocabulary: Vocabulary{
+			Locations: "A location is a path through the OpenAPI object model, dot-separated, with * standing " +
+				"for a map entry (a path, a method, a media type, a property name) and x-* for a specification " +
+				"extension: paths.*.*.requestBody.content.*.schema.maxLength names the maxLength keyword of any " +
+				"request body schema. A claim is location:action[,action...], the edits a change covers; a claim " +
+				"pattern may use ** to cover a location family.",
 			Actions: map[string]string{
 				"add":      "a member is added to a collection (a property, an enum value, a response status)",
 				"remove":   "a member is removed from a collection",
@@ -126,6 +140,27 @@ func main() {
 				"response": "the change concerns what clients receive",
 				"none":     "the change concerns neither side of the wire (metadata, lifecycle)",
 			},
+			Areas: map[string]string{
+				"schema":      "a schema and its keywords, wherever the schema appears",
+				"parameters":  "operation and path parameters",
+				"requestBody": "the request body object and its media types",
+				"responses":   "the responses map, response objects, and their media types",
+				"paths":       "paths, operations, and operation metadata",
+				"headers":     "response headers",
+				"security":    "security schemes, requirements, and scopes",
+				"tags":        "tags and their metadata",
+				"components":  "the components section (compared where referenced)",
+			},
+			Kinds: map[string]string{
+				"existence":    "an element is added or removed",
+				"requiredness": "required, optional, or nullable state",
+				"mutability":   "read-only or write-only state",
+				"type":         "data type or format",
+				"constraints":  "bounds such as min/max, length, items, pattern",
+				"values":       "enum, const, and default values",
+				"structure":    "composition and applicator keywords: allOf, anyOf, oneOf, discriminator, if/then/else, contains",
+				"lifecycle":    "deprecation, sunset, and stability",
+			},
 			Effects: map[string]string{
 				"narrows":      "the new contract rejects payloads the previous contract accepted",
 				"widens":       "the new contract accepts payloads the previous contract rejected",
@@ -147,6 +182,17 @@ func main() {
 				"warning": "plausibly breaking, but the specification cannot decide; the finding says what is missing",
 				"info":    "provably safe for every consumer that conformed to the old contract",
 			},
+			Statuses: map[string]string{
+				"covered":      "one or more named changes claim the edit",
+				"waived":       "no change covers the edit and a written reason says why; the category refines it",
+				"non-contract": "the edit cannot affect which payloads are valid (descriptions, examples, extensions)",
+				"uncovered":    "no change and no waiver; the reference implementation fails its build in this state, so the listing normally contains none",
+			},
+			Categories: map[string]string{
+				"open":              "a missing change, with its reason and a suggested id",
+				"resolved-at-usage": "component definitions are compared at their referencing operations, which have their own rows",
+				"covered-as":        "the same document edit is reported under another action",
+			},
 		},
 		SeverityLaw: SeverityLaw{
 			Description: "A change's level is derived from its effect, its direction, and its guards. " +

openapi-changes-model.yaml

@@ -4,6 +4,7 @@ model: OpenAPI Changes Model
 version: 0.1.0-draft
 generated_from: oasdiff v1.31.0
 vocabulary:
+    locations: 'A location is a path through the OpenAPI object model, dot-separated, with * standing for a map entry (a path, a method, a media type, a property name) and x-* for a specification extension: paths.*.*.requestBody.content.*.schema.maxLength names the maxLength keyword of any request body schema. A claim is location:action[,action...], the edits a change covers; a claim pattern may use ** to cover a location family.'
     actions:
         add: a member is added to a collection (a property, an enum value, a response status)
         change: a field's value is replaced by an incomparable value
@@ -16,6 +17,25 @@ vocabulary:
         none: the change concerns neither side of the wire (metadata, lifecycle)
         request: the change concerns what clients send
         response: the change concerns what clients receive
+    areas:
+        components: the components section (compared where referenced)
+        headers: response headers
+        parameters: operation and path parameters
+        paths: paths, operations, and operation metadata
+        requestBody: the request body object and its media types
+        responses: the responses map, response objects, and their media types
+        schema: a schema and its keywords, wherever the schema appears
+        security: security schemes, requirements, and scopes
+        tags: tags and their metadata
+    kinds:
+        constraints: bounds such as min/max, length, items, pattern
+        existence: an element is added or removed
+        lifecycle: deprecation, sunset, and stability
+        mutability: read-only or write-only state
+        requiredness: required, optional, or nullable state
+        structure: 'composition and applicator keywords: allOf, anyOf, oneOf, discriminator, if/then/else, contains'
+        type: data type or format
+        values: enum, const, and default values
     effects:
         incomparable: the change both rejects previously valid payloads and accepts previously invalid ones
         narrows: the new contract rejects payloads the previous contract accepted
@@ -34,6 +54,15 @@ vocabulary:
         error: a consumer that conformed to the old contract can stop conforming or fail
         info: provably safe for every consumer that conformed to the old contract
         warning: plausibly breaking, but the specification cannot decide; the finding says what is missing
+    statuses:
+        covered: one or more named changes claim the edit
+        non-contract: the edit cannot affect which payloads are valid (descriptions, examples, extensions)
+        uncovered: no change and no waiver; the reference implementation fails its build in this state, so the listing normally contains none
+        waived: no change covers the edit and a written reason says why; the category refines it
+    categories:
+        covered-as: the same document edit is reported under another action
+        open: a missing change, with its reason and a suggested id
+        resolved-at-usage: component definitions are compared at their referencing operations, which have their own rows
 severity_law:
     description: 'A change''s level is derived from its effect, its direction, and its guards. Guards apply first, each nullifying or requalifying the effect on the side it speaks about; then the effect and direction decide: narrowing breaks request consumers, widening breaks response consumers, an incomparable change breaks both, and an unknown one is a warning. When a change cannot be proven safe it is reported as breaking.'
     guards_apply_first: