From 2b622c932da671c438083b1039af8efb5dd8afb5 Mon Sep 17 00:00:00 2001 From: ivanauth Date: Fri, 12 Dec 2025 21:02:26 -0500 Subject: [PATCH] docs: Document UNSPECIFIED enum values that are not returned Add documentation to UNSPECIFIED enum values clarifying they are not valid values and won't be returned in normal operation. Fixes #151 Signed-off-by: ivanauth --- authzed/api/v1/core.proto | 2 ++ authzed/api/v1/debug.proto | 3 +++ authzed/api/v1/permission_service.proto | 3 +++ docs/apidocs.swagger.json | 23 +++++++++++++++-------- 4 files changed, 23 insertions(+), 8 deletions(-) diff --git a/authzed/api/v1/core.proto b/authzed/api/v1/core.proto index 71d7797..a8d61f3 100644 --- a/authzed/api/v1/core.proto +++ b/authzed/api/v1/core.proto @@ -155,6 +155,7 @@ message Cursor { // this operation will no-op. message RelationshipUpdate { enum Operation { + // OPERATION_UNSPECIFIED is not a valid operation and will be rejected. OPERATION_UNSPECIFIED = 0; OPERATION_CREATE = 1; OPERATION_TOUCH = 2; @@ -202,6 +203,7 @@ message PermissionRelationshipTree { // present in the first operand, and none of the other operands. message AlgebraicSubjectSet { enum Operation { + // OPERATION_UNSPECIFIED is not a valid operation and will not be returned. OPERATION_UNSPECIFIED = 0; OPERATION_UNION = 1; OPERATION_INTERSECTION = 2; diff --git a/authzed/api/v1/debug.proto b/authzed/api/v1/debug.proto index 03ae189..ac4a310 100644 --- a/authzed/api/v1/debug.proto +++ b/authzed/api/v1/debug.proto @@ -30,12 +30,14 @@ message DebugInformation { // API call. message CheckDebugTrace { enum PermissionType { + // PERMISSION_TYPE_UNSPECIFIED is not a valid type and will not be returned. PERMISSION_TYPE_UNSPECIFIED = 0; PERMISSION_TYPE_RELATION = 1; PERMISSION_TYPE_PERMISSION = 2; } enum Permissionship { + // PERMISSIONSHIP_UNSPECIFIED is not a valid result and will not be returned. PERMISSIONSHIP_UNSPECIFIED = 0; PERMISSIONSHIP_NO_PERMISSION = 1; PERMISSIONSHIP_HAS_PERMISSION = 2; @@ -130,6 +132,7 @@ message CheckDebugTrace { // CaveatEvalInfo holds information about a caveat expression that was evaluated. message CaveatEvalInfo { enum Result { + // RESULT_UNSPECIFIED is not a valid result and will not be returned. RESULT_UNSPECIFIED = 0; RESULT_UNEVALUATED = 1; diff --git a/authzed/api/v1/permission_service.proto b/authzed/api/v1/permission_service.proto index 8d965af..fc3d321 100644 --- a/authzed/api/v1/permission_service.proto +++ b/authzed/api/v1/permission_service.proto @@ -361,6 +361,7 @@ message ReadRelationshipsResponse { // relationships that match the filter. message Precondition { enum Operation { + // OPERATION_UNSPECIFIED is not a valid operation and will be rejected. OPERATION_UNSPECIFIED = 0; OPERATION_MUST_NOT_MATCH = 1; OPERATION_MUST_MATCH = 2; @@ -455,6 +456,7 @@ message DeleteRelationshipsRequest { message DeleteRelationshipsResponse { enum DeletionProgress { + // DELETION_PROGRESS_UNSPECIFIED is not a valid status and will not be returned. DELETION_PROGRESS_UNSPECIFIED = 0; // DELETION_PROGRESS_COMPLETE indicates that all remaining relationships matching the filter @@ -825,6 +827,7 @@ message LookupResourcesResponse { // which the subject exists, streaming back the IDs of those subjects. message LookupSubjectsRequest { enum WildcardOption { + // WILDCARD_OPTION_UNSPECIFIED is the default and is equivalent to WILDCARD_OPTION_INCLUDE_WILDCARDS. WILDCARD_OPTION_UNSPECIFIED = 0; WILDCARD_OPTION_INCLUDE_WILDCARDS = 1; WILDCARD_OPTION_EXCLUDE_WILDCARDS = 2; diff --git a/docs/apidocs.swagger.json b/docs/apidocs.swagger.json index 6b19cc1..3997d31 100644 --- a/docs/apidocs.swagger.json +++ b/docs/apidocs.swagger.json @@ -1015,7 +1015,8 @@ "OPERATION_INTERSECTION", "OPERATION_EXCLUSION" ], - "default": "OPERATION_UNSPECIFIED" + "default": "OPERATION_UNSPECIFIED", + "description": " - OPERATION_UNSPECIFIED: OPERATION_UNSPECIFIED is not a valid operation and will not be returned." }, "Any": { "type": "object", @@ -1350,7 +1351,8 @@ "PERMISSIONSHIP_HAS_PERMISSION", "PERMISSIONSHIP_CONDITIONAL_PERMISSION" ], - "default": "PERMISSIONSHIP_UNSPECIFIED" + "default": "PERMISSIONSHIP_UNSPECIFIED", + "description": " - PERMISSIONSHIP_UNSPECIFIED: PERMISSIONSHIP_UNSPECIFIED is not a valid result and will not be returned." }, "CheckPermissionRequest": { "type": "object", @@ -1565,7 +1567,7 @@ "DELETION_PROGRESS_PARTIAL" ], "default": "DELETION_PROGRESS_UNSPECIFIED", - "description": " - DELETION_PROGRESS_COMPLETE: DELETION_PROGRESS_COMPLETE indicates that all remaining relationships matching the filter\nwere deleted. Will be returned even if no relationships were deleted.\n - DELETION_PROGRESS_PARTIAL: DELETION_PROGRESS_PARTIAL indicates that a subset of the relationships matching the filter\nwere deleted. Only returned if optional_allow_partial_deletions was true, an optional_limit was\nspecified, and there existed more relationships matching the filter than optional_limit would allow.\nOnce all remaining relationships have been deleted, DELETION_PROGRESS_COMPLETE will be returned." + "description": " - DELETION_PROGRESS_UNSPECIFIED: DELETION_PROGRESS_UNSPECIFIED is not a valid status and will not be returned.\n - DELETION_PROGRESS_COMPLETE: DELETION_PROGRESS_COMPLETE indicates that all remaining relationships matching the filter\nwere deleted. Will be returned even if no relationships were deleted.\n - DELETION_PROGRESS_PARTIAL: DELETION_PROGRESS_PARTIAL indicates that a subset of the relationships matching the filter\nwere deleted. Only returned if optional_allow_partial_deletions was true, an optional_limit was\nspecified, and there existed more relationships matching the filter than optional_limit would allow.\nOnce all remaining relationships have been deleted, DELETION_PROGRESS_COMPLETE will be returned." }, "DependentRelationsRequest": { "type": "object", @@ -2548,7 +2550,8 @@ "PERMISSION_TYPE_RELATION", "PERMISSION_TYPE_PERMISSION" ], - "default": "PERMISSION_TYPE_UNSPECIFIED" + "default": "PERMISSION_TYPE_UNSPECIFIED", + "description": " - PERMISSION_TYPE_UNSPECIFIED: PERMISSION_TYPE_UNSPECIFIED is not a valid type and will not be returned." }, "Precondition": { "type": "object", @@ -2569,7 +2572,8 @@ "OPERATION_MUST_NOT_MATCH", "OPERATION_MUST_MATCH" ], - "default": "OPERATION_UNSPECIFIED" + "default": "OPERATION_UNSPECIFIED", + "description": " - OPERATION_UNSPECIFIED: OPERATION_UNSPECIFIED is not a valid operation and will be rejected." }, "ReadCounterValue": { "type": "object", @@ -3017,7 +3021,8 @@ "OPERATION_TOUCH", "OPERATION_DELETE" ], - "default": "OPERATION_UNSPECIFIED" + "default": "OPERATION_UNSPECIFIED", + "description": " - OPERATION_UNSPECIFIED: OPERATION_UNSPECIFIED is not a valid operation and will be rejected." }, "ResolvedSubject": { "type": "object", @@ -3046,7 +3051,8 @@ "RESULT_TRUE", "RESULT_MISSING_SOME_CONTEXT" ], - "default": "RESULT_UNSPECIFIED" + "default": "RESULT_UNSPECIFIED", + "description": " - RESULT_UNSPECIFIED: RESULT_UNSPECIFIED is not a valid result and will not be returned." }, "SetOperation": { "type": "string", @@ -3278,7 +3284,8 @@ "WILDCARD_OPTION_INCLUDE_WILDCARDS", "WILDCARD_OPTION_EXCLUDE_WILDCARDS" ], - "default": "WILDCARD_OPTION_UNSPECIFIED" + "default": "WILDCARD_OPTION_UNSPECIFIED", + "description": " - WILDCARD_OPTION_UNSPECIFIED: WILDCARD_OPTION_UNSPECIFIED is the default and is equivalent to WILDCARD_OPTION_INCLUDE_WILDCARDS." }, "WriteRelationshipsRequest": { "type": "object",