@openwop/spec-artifacts 2.0.0-rc.0

package/spec/v1/deprecations.schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/deprecations.schema.json",
+  "title": "OpenWOP deprecation register",
+  "description": "Shape of spec/v1/deprecations.json — the index of every surface an RFC or spec annotation has deprecated in v1.x (status: deprecated), plus surfaces the v2 program proposes to deprecate but no RFC has yet (status: proposed). In v1.x the register records deprecations; it never creates one (COMPATIBILITY.md §7). It is not a wire artifact and is deliberately kept out of schemas/.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "version",
+    "updated",
+    "entries"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "./deprecations.schema.json"
+    },
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "updated": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "entries": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/entry"
+      }
+    }
+  },
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "status",
+        "surface",
+        "kind",
+        "deprecatedIn",
+        "authority",
+        "removeIn",
+        "replacement",
+        "codemod",
+        "sources"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^openwop\\.deprecation\\.[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "deprecated",
+            "proposed"
+          ]
+        },
+        "surface": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The wire-visible name of the thing: a field path, a header, a profile id, a schema file, a prose convention."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "discovery-shape",
+            "discovery-field",
+            "profile-id",
+            "header",
+            "schema-field",
+            "prose-convention",
+            "artifact",
+            "error-code",
+            "path"
+          ],
+          "description": "`path` (RFC 0172): an operation path-key surface."
+        },
+        "deprecatedIn": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Corpus or suite version, or the RFC that deprecated it. null when status is proposed."
+        },
+        "authority": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The RFC section or spec annotation that made (or, for proposed, would make) the deprecation."
+        },
+        "removeIn": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+$",
+          "description": "Protocol major.minor at which the surface is removed. v1.x deprecations remove no earlier than 2.0 (COMPATIBILITY.md §7)."
+        },
+        "replacement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "codemod": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Identifier of the codemod that rewrites consumers, once one exists (v2 program C.11)."
+        },
+        "note": {
+          "type": "string"
+        },
+        "sources": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "file",
+              "token"
+            ],
+            "properties": {
+              "file": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Repo-relative path that documents the deprecation (or the surface, for proposed rows)."
+              },
+              "token": {
+                "type": "string",
+                "minLength": 1,
+                "description": "A literal substring the file must still contain; the gate fails when it drifts."
+              }
+            }
+          }
+        },
+        "removalTrigger": {
+          "type": "string",
+          "enum": [
+            "v2.0-cut",
+            "v1-end-of-support"
+          ],
+          "description": "RFC 0176 §C.2: the event that removes the surface. v2.0-cut — absent from the v2 representation from the cut; v1-end-of-support — removed from the v1 representation when every INTEROP-MATRIX host has produced a non-vacuous v2 bundle plus 90 days (charter Phase 0 rule). Optional; removeIn stays the version."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "deprecated"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "deprecatedIn": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "proposed"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "deprecatedIn": {
+                "type": "null"
+              }
+            },
+            "required": [
+              "note"
+            ]
+          }
+        }
+      ]
+    }
+  }
+}