@cleocode/lafs-protocol 0.1.1 → 1.0.0

package/schemas/v1/envelope.schema.json

@@ -3,14 +3,11 @@
   "$id": "https://lafs.dev/schemas/v1/envelope.schema.json",
   "title": "LAFS Envelope v1",
   "type": "object",
-  "additionalProperties": false,
   "required": [
     "$schema",
     "_meta",
     "success",
-    "result",
-    "error",
-    "page"
+    "result"
   ],
   "properties": {
     "$schema": {
@@ -62,11 +59,28 @@
           "type": "boolean"
         },
         "mvi": {
-          "type": "boolean"
+          "type": "string",
+          "enum": ["minimal", "standard", "full", "custom"],
+          "description": "Disclosure level: minimal (MVI only), standard (common fields), full (all fields), custom (per _fields parameter)"
         },
         "contextVersion": {
           "type": "integer",
           "minimum": 0
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": { "type": "string", "description": "Warning identifier (e.g., DEPRECATED_FIELD)" },
+              "message": { "type": "string", "description": "Human-readable warning" },
+              "deprecated": { "type": "string", "description": "The deprecated feature or field name" },
+              "replacement": { "type": "string", "description": "Suggested replacement, if any" },
+              "removeBy": { "type": "string", "description": "Version when the deprecated feature will be removed" }
+            },
+            "required": ["code", "message"]
+          },
+          "description": "Non-fatal advisory warnings (deprecations, migration hints)"
         }
       }
     },
@@ -127,14 +141,7 @@
     "page": {
       "type": ["object", "null"],
       "additionalProperties": false,
-      "required": [
-        "mode",
-        "limit",
-        "offset",
-        "nextCursor",
-        "hasMore",
-        "total"
-      ],
+      "required": ["mode"],
       "properties": {
         "mode": {
           "type": "string",
@@ -160,7 +167,61 @@
           "type": ["integer", "null"],
           "minimum": 0
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "cursor" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode", "nextCursor", "hasMore"],
+            "properties": {
+              "mode": true,
+              "nextCursor": true,
+              "hasMore": true,
+              "limit": true,
+              "total": true
+            }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "offset" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode", "limit", "offset", "hasMore"],
+            "properties": {
+              "mode": true,
+              "limit": true,
+              "offset": true,
+              "hasMore": true,
+              "total": true
+            }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": { "mode": { "const": "none" } },
+            "required": ["mode"]
+          },
+          "then": {
+            "required": ["mode"],
+            "properties": {
+              "mode": true
+            }
+          }
+        }
+      ]
+    },
+    "_extensions": {
+      "type": "object",
+      "description": "Vendor extensions. Keys SHOULD use x- prefix (e.g., x-myvendor-trace-id).",
+      "additionalProperties": true
     }
   },
   "allOf": [
@@ -183,11 +244,39 @@
         }
       },
       "then": {
+        "required": ["error"],
         "properties": {
           "result": { "type": "null" },
           "error": { "type": "object" }
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "_meta": {
+            "type": "object",
+            "properties": {
+              "strict": { "const": true }
+            }
+          }
+        }
+      },
+      "then": {
+        "additionalProperties": false,
+        "properties": {
+          "$schema": true,
+          "_meta": true,
+          "success": true,
+          "result": true,
+          "error": true,
+          "page": true,
+          "_extensions": true
+        }
+      },
+      "else": {
+        "additionalProperties": true
+      }
     }
   ]
 }

package/schemas/v1/error-registry.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "version": "1.0.0",
   "codes": [
     {
@@ -91,6 +91,24 @@
       "httpStatus": 426,
       "grpcStatus": "FAILED_PRECONDITION",
       "cliExit": 10
+    },
+    {
+      "code": "E_DISCLOSURE_UNKNOWN_FIELD",
+      "category": "VALIDATION",
+      "description": "Unrecognized expansion field in _expand parameter",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2
+    },
+    {
+      "code": "E_MVI_BUDGET_EXCEEDED",
+      "category": "VALIDATION",
+      "description": "Response exceeds declared MVI budget (token, byte, or item limit)",
+      "retryable": false,
+      "httpStatus": 413,
+      "grpcStatus": "RESOURCE_EXHAUSTED",
+      "cliExit": 2
     }
   ]
 }