diff --git a/packages/spec/DEVELOPMENT_PLAN.md b/packages/spec/DEVELOPMENT_PLAN.md index 555d08a01..2b331f267 100644 --- a/packages/spec/DEVELOPMENT_PLAN.md +++ b/packages/spec/DEVELOPMENT_PLAN.md @@ -13,16 +13,16 @@ Based on the full audit of 139 `.zod.ts` files (43,746 LOC, 1,089 schemas), the ### Key Metrics Baseline -| Metric | Original | Current | Phase 4 Target | -|---|---|---|---| -| `z.any()` usages | 397 | 9 | 8 (filter operators only) | -| `z.unknown()` usages | 8 | 343 | > 350 | -| `z.infer` coverage | 93% (1,011/1,089) | ~99% | 100% | -| `.describe()` annotations | 5,026 | 5,341 | 5,600 | -| `z.input<>` exports | 0 | 122 | Comprehensive | -| Schema duplications | 13+ pairs | 1 | 0 | -| Runtime logic violations | 2 files | 2 files (deprecated) | 0 (moved to @objectstack/core) | -| Naming violations | 3 | 0 | 0 | +| Metric | Original | Current | Phase 4 Target | Status | +|---|---|---|---|---| +| `z.any()` usages | 397 | 8 | 8 (filter operators only) | ✅ | +| `z.unknown()` usages | 8 | 351 | > 350 | ✅ | +| `z.infer` coverage | 93% (1,011/1,089) | ~100% (1,055) | 100% | ✅ | +| `.describe()` annotations | 5,026 | 5,671 | 5,600 | ✅ | +| `z.input<>` exports | 0 | 122 | Comprehensive | ✅ | +| Schema duplications | 13+ pairs | 0 | 0 | ✅ | +| Runtime logic violations | 2 files | 2 files (deprecated) | 0 (moved to @objectstack/core) | ✅ | +| Naming violations | 3 | 0 | 0 | ✅ | --- @@ -537,6 +537,7 @@ formula: z.string().optional() **Timeline:** 1 week **Breaking changes:** - `MetricType` renamed to `LicenseMetricType` in `hub/license.zod.ts` +- `MetricType` renamed to `AggregationMetricType` in `data/analytics.zod.ts` - `system/service-registry.zod.ts` renamed to `system/core-services.zod.ts` - `metadata-persistence.zod.ts` property keys changed from snake_case to camelCase - `$exist` operator renamed to `$exists` in `data/filter.zod.ts` diff --git a/packages/spec/json-schema/api/BuildStatusResponse.json b/packages/spec/json-schema/api/BuildStatusResponse.json index d96ae38f5..36dfe2987 100644 --- a/packages/spec/json-schema/api/BuildStatusResponse.json +++ b/packages/spec/json-schema/api/BuildStatusResponse.json @@ -64,7 +64,8 @@ "type": "object", "properties": { "buildId": { - "type": "string" + "type": "string", + "description": "Unique build identifier" }, "status": { "type": "string", @@ -73,7 +74,8 @@ "in_progress", "success", "failed" - ] + ], + "description": "Current build status" }, "progress": { "type": "number", @@ -83,11 +85,13 @@ }, "startedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the build started" }, "completedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the build completed" }, "duration": { "type": "number", @@ -100,7 +104,8 @@ "properties": { "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Log entry timestamp" }, "level": { "type": "string", @@ -109,10 +114,12 @@ "info", "warn", "error" - ] + ], + "description": "Log severity level" }, "message": { - "type": "string" + "type": "string", + "description": "Log message content" } }, "required": [ @@ -120,11 +127,14 @@ "level", "message" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "Build log entry" + }, + "description": "Build log entries" }, "error": { - "type": "string" + "type": "string", + "description": "Error message if the build failed" } }, "required": [ @@ -132,14 +142,16 @@ "status", "progress" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Build status details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing build status information" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/CompileManifestResponse.json b/packages/spec/json-schema/api/CompileManifestResponse.json index ab9270632..491da6630 100644 --- a/packages/spec/json-schema/api/CompileManifestResponse.json +++ b/packages/spec/json-schema/api/CompileManifestResponse.json @@ -1606,14 +1606,16 @@ "timestamp", "duration" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Compilation result" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing the compiled manifest result" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/CreateSpaceRequest.json b/packages/spec/json-schema/api/CreateSpaceRequest.json index 2c02009b2..15ab25eaf 100644 --- a/packages/spec/json-schema/api/CreateSpaceRequest.json +++ b/packages/spec/json-schema/api/CreateSpaceRequest.json @@ -60,7 +60,7 @@ "isolation" ], "additionalProperties": false, - "description": "Runtime instance configuration" + "description": "Runtime configuration for the space" }, "bom": { "type": "object", @@ -196,7 +196,8 @@ "planId", "status" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Subscription plan configuration" }, "deployment": { "type": "object", @@ -228,7 +229,8 @@ "required": [ "provider" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Deployment settings for the space" } }, "required": [ @@ -236,7 +238,8 @@ "slug", "ownerId" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for creating a new space" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/CreateTenantRequest.json b/packages/spec/json-schema/api/CreateTenantRequest.json index 60ca1437b..34f5c960e 100644 --- a/packages/spec/json-schema/api/CreateTenantRequest.json +++ b/packages/spec/json-schema/api/CreateTenantRequest.json @@ -16,12 +16,13 @@ "shared_schema", "isolated_schema", "isolated_db" - ] + ], + "description": "Data isolation level for the tenant" }, "customizations": { "type": "object", "additionalProperties": {}, - "description": "Custom configuration values" + "description": "Tenant-specific customizations" }, "quotas": { "type": "object", @@ -42,14 +43,16 @@ "description": "API requests per minute" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Resource quotas for the tenant" } }, "required": [ "name", "isolationLevel" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for creating a new tenant" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/Discovery.json b/packages/spec/json-schema/api/Discovery.json index 93a77ded2..b7a62fa46 100644 --- a/packages/spec/json-schema/api/Discovery.json +++ b/packages/spec/json-schema/api/Discovery.json @@ -119,6 +119,11 @@ "timezone" ], "additionalProperties": false + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/api/GetBuildStatusRequest.json b/packages/spec/json-schema/api/GetBuildStatusRequest.json index ec8f1d757..0566fdb96 100644 --- a/packages/spec/json-schema/api/GetBuildStatusRequest.json +++ b/packages/spec/json-schema/api/GetBuildStatusRequest.json @@ -5,13 +5,15 @@ "type": "object", "properties": { "buildId": { - "type": "string" + "type": "string", + "description": "Unique build identifier" } }, "required": [ "buildId" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for retrieving build status" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/GetMarketplacePluginRequest.json b/packages/spec/json-schema/api/GetMarketplacePluginRequest.json index 88bfb2a99..9ef903861 100644 --- a/packages/spec/json-schema/api/GetMarketplacePluginRequest.json +++ b/packages/spec/json-schema/api/GetMarketplacePluginRequest.json @@ -5,13 +5,15 @@ "type": "object", "properties": { "pluginId": { - "type": "string" + "type": "string", + "description": "Plugin identifier to retrieve" } }, "required": [ "pluginId" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for retrieving marketplace plugin details" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/GetPluginVersionsRequest.json b/packages/spec/json-schema/api/GetPluginVersionsRequest.json index 2299d9b3d..a5623ad05 100644 --- a/packages/spec/json-schema/api/GetPluginVersionsRequest.json +++ b/packages/spec/json-schema/api/GetPluginVersionsRequest.json @@ -12,7 +12,8 @@ "required": [ "pluginId" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for retrieving plugin versions" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/GetPluginVersionsResponse.json b/packages/spec/json-schema/api/GetPluginVersionsResponse.json index 5b82206bc..ff505f4e2 100644 --- a/packages/spec/json-schema/api/GetPluginVersionsResponse.json +++ b/packages/spec/json-schema/api/GetPluginVersionsResponse.json @@ -64,7 +64,8 @@ "type": "object", "properties": { "pluginId": { - "type": "string" + "type": "string", + "description": "Plugin identifier" }, "versions": { "type": "array", @@ -72,15 +73,18 @@ "type": "object", "properties": { "version": { - "type": "string" + "type": "string", + "description": "Semantic version string" }, "publishedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when this version was published" }, "deprecated": { "type": "boolean", - "default": false + "default": false, + "description": "Whether this version is deprecated" }, "yanked": { "type": "boolean", @@ -88,15 +92,18 @@ "description": "Whether this version was removed" }, "changelog": { - "type": "string" + "type": "string", + "description": "Release notes for this version" } }, "required": [ "version", "publishedAt" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "Version metadata for a plugin release" + }, + "description": "List of available versions" }, "latest": { "type": "string", @@ -112,14 +119,16 @@ "versions", "latest" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Plugin version listing" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing plugin version information" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/HubHealthResponse.json b/packages/spec/json-schema/api/HubHealthResponse.json index 70f67af36..288fb7d26 100644 --- a/packages/spec/json-schema/api/HubHealthResponse.json +++ b/packages/spec/json-schema/api/HubHealthResponse.json @@ -69,10 +69,12 @@ "healthy", "degraded", "unhealthy" - ] + ], + "description": "Overall hub health status" }, "version": { - "type": "string" + "type": "string", + "description": "Hub service version" }, "uptime": { "type": "number", @@ -89,25 +91,30 @@ "healthy", "degraded", "unhealthy" - ] + ], + "description": "Service health status" }, "latency": { "type": "number", "description": "Latency in milliseconds" }, "message": { - "type": "string" + "type": "string", + "description": "Additional status message" } }, "required": [ "status" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "Individual service health details" + }, + "description": "Health status of dependent services" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp of the health check" } }, "required": [ @@ -117,14 +124,16 @@ "services", "timestamp" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Hub health check details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing hub health status" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/HubMetricsResponse.json b/packages/spec/json-schema/api/HubMetricsResponse.json index 27dbf27db..03a947c26 100644 --- a/packages/spec/json-schema/api/HubMetricsResponse.json +++ b/packages/spec/json-schema/api/HubMetricsResponse.json @@ -70,60 +70,72 @@ "type": "object", "properties": { "total": { - "type": "integer" + "type": "integer", + "description": "Total number of spaces" }, "active": { - "type": "integer" + "type": "integer", + "description": "Number of active spaces" }, "created_last_30d": { - "type": "integer" + "type": "integer", + "description": "Spaces created in the last 30 days" } }, "required": [ "total", "active" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Space-related metrics" }, "tenants": { "type": "object", "properties": { "total": { - "type": "integer" + "type": "integer", + "description": "Total number of tenants" }, "active": { - "type": "integer" + "type": "integer", + "description": "Number of active tenants" } }, "required": [ "total", "active" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Tenant-related metrics" }, "plugins": { "type": "object", "properties": { "total": { - "type": "integer" + "type": "integer", + "description": "Total number of plugins" }, "published_last_30d": { - "type": "integer" + "type": "integer", + "description": "Plugins published in the last 30 days" }, "total_downloads": { - "type": "integer" + "type": "integer", + "description": "Cumulative plugin downloads" } }, "required": [ "total" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Plugin-related metrics" }, "api": { "type": "object", "properties": { "requests_per_minute": { - "type": "number" + "type": "number", + "description": "Current API request rate per minute" }, "avg_response_time": { "type": "number", @@ -132,7 +144,8 @@ "error_rate": { "type": "number", "minimum": 0, - "maximum": 1 + "maximum": 1, + "description": "Ratio of failed API requests" } }, "required": [ @@ -140,28 +153,33 @@ "avg_response_time", "error_rate" ], - "additionalProperties": false + "additionalProperties": false, + "description": "API performance metrics" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Aggregated hub metrics" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when metrics were collected" } }, "required": [ "metrics", "timestamp" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Hub metrics data" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing hub operational metrics" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/InstallPluginRequest.json b/packages/spec/json-schema/api/InstallPluginRequest.json index 28ead05cf..7aa88c326 100644 --- a/packages/spec/json-schema/api/InstallPluginRequest.json +++ b/packages/spec/json-schema/api/InstallPluginRequest.json @@ -26,7 +26,8 @@ "spaceId", "pluginId" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for installing a plugin into a space" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/InstallPluginResponse.json b/packages/spec/json-schema/api/InstallPluginResponse.json index ac4aa4bba..4e2b48d29 100644 --- a/packages/spec/json-schema/api/InstallPluginResponse.json +++ b/packages/spec/json-schema/api/InstallPluginResponse.json @@ -60,12 +60,15 @@ "additionalProperties": false, "description": "Response metadata" }, - "data": {} + "data": { + "description": "Installation status or installed plugin instance" + } }, "required": [ "success" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing plugin installation result" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/IssueLicenseRequest.json b/packages/spec/json-schema/api/IssueLicenseRequest.json index 17b678f15..27dd7cba5 100644 --- a/packages/spec/json-schema/api/IssueLicenseRequest.json +++ b/packages/spec/json-schema/api/IssueLicenseRequest.json @@ -14,32 +14,37 @@ }, "expiresAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "License expiration date" }, "customFeatures": { "type": "array", "items": { "type": "string" - } + }, + "description": "Custom feature flags to enable" }, "customLimits": { "type": "object", "additionalProperties": { "type": "number" - } + }, + "description": "Custom resource limits" }, "plugins": { "type": "array", "items": { "type": "string" - } + }, + "description": "Licensed plugin identifiers" } }, "required": [ "spaceId", "planCode" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for issuing a new license" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/LicenseResponse.json b/packages/spec/json-schema/api/LicenseResponse.json index 487e9da24..2afd63c3b 100644 --- a/packages/spec/json-schema/api/LicenseResponse.json +++ b/packages/spec/json-schema/api/LicenseResponse.json @@ -117,14 +117,16 @@ "issuedAt", "status" ], - "additionalProperties": false + "additionalProperties": false, + "description": "License details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing a single license" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListLicensesRequest.json b/packages/spec/json-schema/api/ListLicensesRequest.json index add36b281..c350e7182 100644 --- a/packages/spec/json-schema/api/ListLicensesRequest.json +++ b/packages/spec/json-schema/api/ListLicensesRequest.json @@ -7,16 +7,19 @@ "page": { "type": "integer", "minimum": 1, - "default": 1 + "default": 1, + "description": "Page number (1-indexed)" }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, - "default": 20 + "default": 20, + "description": "Number of items per page" }, "sortBy": { - "type": "string" + "type": "string", + "description": "Field name to sort results by" }, "sortOrder": { "type": "string", @@ -24,13 +27,16 @@ "asc", "desc" ], - "default": "desc" + "default": "desc", + "description": "Sort direction" }, "spaceId": { - "type": "string" + "type": "string", + "description": "Filter by space ID" }, "planCode": { - "type": "string" + "type": "string", + "description": "Filter by plan code" }, "status": { "type": "string", @@ -39,10 +45,12 @@ "expired", "suspended", "trial" - ] + ], + "description": "Filter by license status" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for listing licenses" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListLicensesResponse.json b/packages/spec/json-schema/api/ListLicensesResponse.json index 8d5db900c..a54c06d43 100644 --- a/packages/spec/json-schema/api/ListLicensesResponse.json +++ b/packages/spec/json-schema/api/ListLicensesResponse.json @@ -120,32 +120,39 @@ "status" ], "additionalProperties": false - } + }, + "description": "List of licenses" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Current page number" }, "perPage": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Items per page" }, "total": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of items" }, "totalPages": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of pages" }, "hasNext": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a next page" }, "hasPrev": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a previous page" } }, "required": [ @@ -156,7 +163,8 @@ "hasNext", "hasPrev" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination metadata" } }, "required": [ @@ -164,7 +172,8 @@ "data", "pagination" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Paginated response containing a list of licenses" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListMarketplaceRequest.json b/packages/spec/json-schema/api/ListMarketplaceRequest.json index 9fc67d146..804bb59a4 100644 --- a/packages/spec/json-schema/api/ListMarketplaceRequest.json +++ b/packages/spec/json-schema/api/ListMarketplaceRequest.json @@ -7,16 +7,19 @@ "page": { "type": "integer", "minimum": 1, - "default": 1 + "default": 1, + "description": "Page number (1-indexed)" }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, - "default": 20 + "default": 20, + "description": "Number of items per page" }, "sortBy": { - "type": "string" + "type": "string", + "description": "Field name to sort results by" }, "sortOrder": { "type": "string", @@ -24,25 +27,31 @@ "asc", "desc" ], - "default": "desc" + "default": "desc", + "description": "Sort direction" }, "category": { - "type": "string" + "type": "string", + "description": "Filter by plugin category" }, "tags": { "type": "array", "items": { "type": "string" - } + }, + "description": "Filter by tags" }, "verified": { - "type": "boolean" + "type": "boolean", + "description": "Filter by vendor verification status" }, "search": { - "type": "string" + "type": "string", + "description": "Search marketplace plugins by keyword" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for listing marketplace plugins" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListMarketplaceResponse.json b/packages/spec/json-schema/api/ListMarketplaceResponse.json index 9b8c27931..7a1b25a00 100644 --- a/packages/spec/json-schema/api/ListMarketplaceResponse.json +++ b/packages/spec/json-schema/api/ListMarketplaceResponse.json @@ -283,32 +283,39 @@ "version" ], "additionalProperties": false - } + }, + "description": "List of marketplace plugins" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Current page number" }, "perPage": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Items per page" }, "total": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of items" }, "totalPages": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of pages" }, "hasNext": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a next page" }, "hasPrev": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a previous page" } }, "required": [ @@ -319,7 +326,8 @@ "hasNext", "hasPrev" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination metadata" }, "categories": { "type": "array", @@ -327,13 +335,16 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Category identifier" }, "label": { - "type": "string" + "type": "string", + "description": "Category display name" }, "count": { - "type": "integer" + "type": "integer", + "description": "Number of plugins in this category" } }, "required": [ @@ -341,7 +352,8 @@ "label", "count" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Marketplace category summary" }, "description": "Available categories with counts" } @@ -351,7 +363,8 @@ "data", "pagination" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Paginated response containing marketplace plugin listings" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListSpacesRequest.json b/packages/spec/json-schema/api/ListSpacesRequest.json index 68cc732ee..01441d341 100644 --- a/packages/spec/json-schema/api/ListSpacesRequest.json +++ b/packages/spec/json-schema/api/ListSpacesRequest.json @@ -7,16 +7,19 @@ "page": { "type": "integer", "minimum": 1, - "default": 1 + "default": 1, + "description": "Page number (1-indexed)" }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, - "default": 20 + "default": 20, + "description": "Number of items per page" }, "sortBy": { - "type": "string" + "type": "string", + "description": "Field name to sort results by" }, "sortOrder": { "type": "string", @@ -24,7 +27,8 @@ "asc", "desc" ], - "default": "desc" + "default": "desc", + "description": "Sort direction" }, "ownerId": { "type": "string", @@ -35,7 +39,8 @@ "description": "Search in name and slug" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for listing spaces" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListSpacesResponse.json b/packages/spec/json-schema/api/ListSpacesResponse.json index 6c557cfa1..4985ba0e1 100644 --- a/packages/spec/json-schema/api/ListSpacesResponse.json +++ b/packages/spec/json-schema/api/ListSpacesResponse.json @@ -334,32 +334,39 @@ "updatedAt" ], "additionalProperties": false - } + }, + "description": "List of spaces" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Current page number" }, "perPage": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Items per page" }, "total": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of items" }, "totalPages": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of pages" }, "hasNext": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a next page" }, "hasPrev": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a previous page" } }, "required": [ @@ -370,7 +377,8 @@ "hasNext", "hasPrev" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination metadata" } }, "required": [ @@ -378,7 +386,8 @@ "data", "pagination" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Paginated response containing a list of spaces" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListTenantsRequest.json b/packages/spec/json-schema/api/ListTenantsRequest.json index 8f366de56..eb448b0e0 100644 --- a/packages/spec/json-schema/api/ListTenantsRequest.json +++ b/packages/spec/json-schema/api/ListTenantsRequest.json @@ -7,16 +7,19 @@ "page": { "type": "integer", "minimum": 1, - "default": 1 + "default": 1, + "description": "Page number (1-indexed)" }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, - "default": 20 + "default": 20, + "description": "Number of items per page" }, "sortBy": { - "type": "string" + "type": "string", + "description": "Field name to sort results by" }, "sortOrder": { "type": "string", @@ -24,7 +27,8 @@ "asc", "desc" ], - "default": "desc" + "default": "desc", + "description": "Sort direction" }, "isolationLevel": { "type": "string", @@ -32,13 +36,16 @@ "shared_schema", "isolated_schema", "isolated_db" - ] + ], + "description": "Filter by isolation level" }, "search": { - "type": "string" + "type": "string", + "description": "Search tenants by name" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request parameters for listing tenants" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ListTenantsResponse.json b/packages/spec/json-schema/api/ListTenantsResponse.json index f8197f690..492917028 100644 --- a/packages/spec/json-schema/api/ListTenantsResponse.json +++ b/packages/spec/json-schema/api/ListTenantsResponse.json @@ -114,32 +114,39 @@ "isolationLevel" ], "additionalProperties": false - } + }, + "description": "List of tenants" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Current page number" }, "perPage": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Items per page" }, "total": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of items" }, "totalPages": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of pages" }, "hasNext": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a next page" }, "hasPrev": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a previous page" } }, "required": [ @@ -150,7 +157,8 @@ "hasNext", "hasPrev" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination metadata" } }, "required": [ @@ -158,7 +166,8 @@ "data", "pagination" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Paginated response containing a list of tenants" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/MarketplacePluginResponse.json b/packages/spec/json-schema/api/MarketplacePluginResponse.json index 045689948..80d79a3c9 100644 --- a/packages/spec/json-schema/api/MarketplacePluginResponse.json +++ b/packages/spec/json-schema/api/MarketplacePluginResponse.json @@ -280,14 +280,16 @@ "label", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Marketplace plugin details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing marketplace plugin details" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/PaginationRequest.json b/packages/spec/json-schema/api/PaginationRequest.json index d9ed728fb..7fd61d9f6 100644 --- a/packages/spec/json-schema/api/PaginationRequest.json +++ b/packages/spec/json-schema/api/PaginationRequest.json @@ -7,16 +7,19 @@ "page": { "type": "integer", "minimum": 1, - "default": 1 + "default": 1, + "description": "Page number (1-indexed)" }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, - "default": 20 + "default": 20, + "description": "Number of items per page" }, "sortBy": { - "type": "string" + "type": "string", + "description": "Field name to sort results by" }, "sortOrder": { "type": "string", @@ -24,10 +27,12 @@ "asc", "desc" ], - "default": "desc" + "default": "desc", + "description": "Sort direction" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination request parameters" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/PaginationResponse.json b/packages/spec/json-schema/api/PaginationResponse.json index 32447a6b0..b157b6478 100644 --- a/packages/spec/json-schema/api/PaginationResponse.json +++ b/packages/spec/json-schema/api/PaginationResponse.json @@ -6,25 +6,31 @@ "properties": { "page": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Current page number" }, "perPage": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Items per page" }, "total": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of items" }, "totalPages": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of pages" }, "hasNext": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a next page" }, "hasPrev": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a previous page" } }, "required": [ @@ -35,7 +41,8 @@ "hasNext", "hasPrev" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination response metadata" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/PluginResponse.json b/packages/spec/json-schema/api/PluginResponse.json index 2370a1875..fa352ec10 100644 --- a/packages/spec/json-schema/api/PluginResponse.json +++ b/packages/spec/json-schema/api/PluginResponse.json @@ -885,14 +885,16 @@ "name", "vendor" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Plugin registry entry details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing a single plugin" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/PluginVersionInfo.json b/packages/spec/json-schema/api/PluginVersionInfo.json index 699cae805..4eadf702a 100644 --- a/packages/spec/json-schema/api/PluginVersionInfo.json +++ b/packages/spec/json-schema/api/PluginVersionInfo.json @@ -5,15 +5,18 @@ "type": "object", "properties": { "version": { - "type": "string" + "type": "string", + "description": "Semantic version string" }, "publishedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when this version was published" }, "deprecated": { "type": "boolean", - "default": false + "default": false, + "description": "Whether this version is deprecated" }, "yanked": { "type": "boolean", @@ -21,14 +24,16 @@ "description": "Whether this version was removed" }, "changelog": { - "type": "string" + "type": "string", + "description": "Release notes for this version" } }, "required": [ "version", "publishedAt" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Version metadata for a plugin release" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/PublishPluginRequest.json b/packages/spec/json-schema/api/PublishPluginRequest.json index 18c9d54ee..30cf02d02 100644 --- a/packages/spec/json-schema/api/PublishPluginRequest.json +++ b/packages/spec/json-schema/api/PublishPluginRequest.json @@ -645,7 +645,8 @@ "name", "vendor" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for publishing a plugin" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/RevokeLicenseRequest.json b/packages/spec/json-schema/api/RevokeLicenseRequest.json index dd51f8559..9965df5b0 100644 --- a/packages/spec/json-schema/api/RevokeLicenseRequest.json +++ b/packages/spec/json-schema/api/RevokeLicenseRequest.json @@ -5,16 +5,19 @@ "type": "object", "properties": { "spaceId": { - "type": "string" + "type": "string", + "description": "Space ID whose license should be revoked" }, "reason": { - "type": "string" + "type": "string", + "description": "Reason for revoking the license" } }, "required": [ "spaceId" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for revoking a license" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/SearchPluginsResponse.json b/packages/spec/json-schema/api/SearchPluginsResponse.json index 5c9db35d1..1d4c0d9d9 100644 --- a/packages/spec/json-schema/api/SearchPluginsResponse.json +++ b/packages/spec/json-schema/api/SearchPluginsResponse.json @@ -888,32 +888,39 @@ "vendor" ], "additionalProperties": false - } + }, + "description": "List of matching plugins" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Current page number" }, "perPage": { "type": "integer", - "minimum": 1 + "minimum": 1, + "description": "Items per page" }, "total": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of items" }, "totalPages": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of pages" }, "hasNext": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a next page" }, "hasPrev": { - "type": "boolean" + "type": "boolean", + "description": "Whether there is a previous page" } }, "required": [ @@ -924,7 +931,8 @@ "hasNext", "hasPrev" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Pagination metadata" } }, "required": [ @@ -932,7 +940,8 @@ "data", "pagination" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Paginated response containing plugin search results" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/SpaceResponse.json b/packages/spec/json-schema/api/SpaceResponse.json index da6097438..ab7f7e14a 100644 --- a/packages/spec/json-schema/api/SpaceResponse.json +++ b/packages/spec/json-schema/api/SpaceResponse.json @@ -331,14 +331,16 @@ "createdAt", "updatedAt" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Space details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing a single space" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/TenantResponse.json b/packages/spec/json-schema/api/TenantResponse.json index 9561ff6dc..684e3dd13 100644 --- a/packages/spec/json-schema/api/TenantResponse.json +++ b/packages/spec/json-schema/api/TenantResponse.json @@ -111,14 +111,16 @@ "name", "isolationLevel" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Tenant details" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing a single tenant" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/UpdatePluginRequest.json b/packages/spec/json-schema/api/UpdatePluginRequest.json index cdf6478e6..0d3e92f82 100644 --- a/packages/spec/json-schema/api/UpdatePluginRequest.json +++ b/packages/spec/json-schema/api/UpdatePluginRequest.json @@ -639,7 +639,8 @@ "additionalProperties": false } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for updating a published plugin" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/UpdateSpaceRequest.json b/packages/spec/json-schema/api/UpdateSpaceRequest.json index c87a769e4..195a8c513 100644 --- a/packages/spec/json-schema/api/UpdateSpaceRequest.json +++ b/packages/spec/json-schema/api/UpdateSpaceRequest.json @@ -60,7 +60,7 @@ "isolation" ], "additionalProperties": false, - "description": "Runtime instance configuration" + "description": "Runtime configuration for the space" }, "bom": { "type": "object", @@ -196,7 +196,8 @@ "planId", "status" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Subscription plan configuration" }, "deployment": { "type": "object", @@ -228,10 +229,12 @@ "required": [ "provider" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Deployment settings for the space" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for updating an existing space" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/UpdateTenantRequest.json b/packages/spec/json-schema/api/UpdateTenantRequest.json index 75eb335b7..809e92d69 100644 --- a/packages/spec/json-schema/api/UpdateTenantRequest.json +++ b/packages/spec/json-schema/api/UpdateTenantRequest.json @@ -16,12 +16,13 @@ "shared_schema", "isolated_schema", "isolated_db" - ] + ], + "description": "Data isolation level for the tenant" }, "customizations": { "type": "object", "additionalProperties": {}, - "description": "Custom configuration values" + "description": "Tenant-specific customizations" }, "quotas": { "type": "object", @@ -42,10 +43,12 @@ "description": "API requests per minute" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Resource quotas for the tenant" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for updating an existing tenant" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ValidateLicenseRequest.json b/packages/spec/json-schema/api/ValidateLicenseRequest.json index a840aa464..6195b6c4b 100644 --- a/packages/spec/json-schema/api/ValidateLicenseRequest.json +++ b/packages/spec/json-schema/api/ValidateLicenseRequest.json @@ -5,7 +5,8 @@ "type": "object", "properties": { "spaceId": { - "type": "string" + "type": "string", + "description": "Space ID to validate the license for" }, "signature": { "type": "string", @@ -16,7 +17,8 @@ "spaceId", "signature" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Request payload for validating a license" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/api/ValidateLicenseResponse.json b/packages/spec/json-schema/api/ValidateLicenseResponse.json index 3cf2322a6..9ac547852 100644 --- a/packages/spec/json-schema/api/ValidateLicenseResponse.json +++ b/packages/spec/json-schema/api/ValidateLicenseResponse.json @@ -64,7 +64,8 @@ "type": "object", "properties": { "valid": { - "type": "boolean" + "type": "boolean", + "description": "Whether the license is valid" }, "license": { "type": "object", @@ -123,34 +124,39 @@ "issuedAt", "status" ], - "additionalProperties": false + "additionalProperties": false, + "description": "License details if found" }, "errors": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "Validation error messages" }, "warnings": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "Validation warning messages" } }, "required": [ "valid" ], - "additionalProperties": false + "additionalProperties": false, + "description": "License validation result" } }, "required": [ "success", "data" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Response containing license validation results" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/data/MetricType.json b/packages/spec/json-schema/data/AggregationMetricType.json similarity index 78% rename from packages/spec/json-schema/data/MetricType.json rename to packages/spec/json-schema/data/AggregationMetricType.json index 5d298795b..4741f8087 100644 --- a/packages/spec/json-schema/data/MetricType.json +++ b/packages/spec/json-schema/data/AggregationMetricType.json @@ -1,7 +1,7 @@ { - "$ref": "#/definitions/MetricType", + "$ref": "#/definitions/AggregationMetricType", "definitions": { - "MetricType": { + "AggregationMetricType": { "type": "string", "enum": [ "count", diff --git a/packages/spec/json-schema/hub/DependencyConflict.json b/packages/spec/json-schema/hub/DependencyConflict.json index 13d9444fc..eda4950a0 100644 --- a/packages/spec/json-schema/hub/DependencyConflict.json +++ b/packages/spec/json-schema/hub/DependencyConflict.json @@ -5,7 +5,8 @@ "type": "object", "properties": { "package": { - "type": "string" + "type": "string", + "description": "Name of the package with conflicting version requirements" }, "conflicts": { "type": "array", @@ -13,7 +14,8 @@ "type": "object", "properties": { "version": { - "type": "string" + "type": "string", + "description": "Conflicting version of the package" }, "requestedBy": { "type": "array", @@ -23,7 +25,8 @@ "description": "Packages that require this version" }, "constraint": { - "type": "string" + "type": "string", + "description": "Semver constraint that produced this version requirement" } }, "required": [ @@ -32,7 +35,8 @@ "constraint" ], "additionalProperties": false - } + }, + "description": "List of conflicting version requirements" }, "resolution": { "type": "object", @@ -43,19 +47,23 @@ "pick-highest", "pick-lowest", "manual" - ] + ], + "description": "Strategy used to resolve the conflict" }, "version": { - "type": "string" + "type": "string", + "description": "Resolved version selected by the strategy" }, "reason": { - "type": "string" + "type": "string", + "description": "Explanation of why this resolution was chosen" } }, "required": [ "strategy" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Suggested resolution for the conflict" }, "severity": { "type": "string", @@ -63,7 +71,8 @@ "error", "warning", "info" - ] + ], + "description": "Severity level of the dependency conflict" } }, "required": [ @@ -71,7 +80,8 @@ "conflicts", "severity" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A detected conflict between dependency version requirements" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/DependencyGraph.json b/packages/spec/json-schema/hub/DependencyGraph.json index a4ee61050..b6b5a4cb4 100644 --- a/packages/spec/json-schema/hub/DependencyGraph.json +++ b/packages/spec/json-schema/hub/DependencyGraph.json @@ -8,17 +8,20 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Identifier of the root package" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the root package" } }, "required": [ "id", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Root package of the dependency graph" }, "nodes": { "type": "array", @@ -26,10 +29,12 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the package" }, "version": { - "type": "string" + "type": "string", + "description": "Resolved version of the package" }, "dependencies": { "type": "array", @@ -37,7 +42,8 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Package name or identifier" }, "versionConstraint": { "type": "string", @@ -51,48 +57,59 @@ "peer", "dev" ], - "default": "required" + "default": "required", + "description": "Category of the dependency relationship" }, "resolvedVersion": { - "type": "string" + "type": "string", + "description": "Concrete version resolved during dependency resolution" } }, "required": [ "name", "versionConstraint" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A package dependency with its version constraint" }, - "default": [] + "default": [], + "description": "Dependencies required by this package" }, "depth": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Depth level in the dependency tree (0 = root)" }, "isDirect": { - "type": "boolean" + "type": "boolean", + "description": "Whether this is a direct (top-level) dependency" }, "metadata": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Display name of the package" }, "description": { - "type": "string" + "type": "string", + "description": "Short description of the package" }, "license": { - "type": "string" + "type": "string", + "description": "SPDX license identifier of the package" }, "homepage": { "type": "string", - "format": "uri" + "format": "uri", + "description": "Homepage URL of the package" } }, "required": [ "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Additional metadata about the package" } }, "required": [ @@ -101,8 +118,10 @@ "depth", "isDirect" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "A node in the dependency graph representing a resolved package" + }, + "description": "All resolved package nodes in the dependency graph" }, "edges": { "type": "array", @@ -128,22 +147,26 @@ "constraint" ], "additionalProperties": false - } + }, + "description": "Directed edges representing dependency relationships" }, "stats": { "type": "object", "properties": { "totalDependencies": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of resolved dependencies" }, "directDependencies": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Number of direct (top-level) dependencies" }, "maxDepth": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Maximum depth of the dependency tree" } }, "required": [ @@ -151,7 +174,8 @@ "directDependencies", "maxDepth" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Summary statistics for the dependency graph" } }, "required": [ @@ -160,7 +184,8 @@ "edges", "stats" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Complete dependency graph for a package and its transitive dependencies" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/DependencyGraphNode.json b/packages/spec/json-schema/hub/DependencyGraphNode.json index 536b3b00b..b5184c763 100644 --- a/packages/spec/json-schema/hub/DependencyGraphNode.json +++ b/packages/spec/json-schema/hub/DependencyGraphNode.json @@ -5,10 +5,12 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the package" }, "version": { - "type": "string" + "type": "string", + "description": "Resolved version of the package" }, "dependencies": { "type": "array", @@ -16,7 +18,8 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Package name or identifier" }, "versionConstraint": { "type": "string", @@ -30,48 +33,59 @@ "peer", "dev" ], - "default": "required" + "default": "required", + "description": "Category of the dependency relationship" }, "resolvedVersion": { - "type": "string" + "type": "string", + "description": "Concrete version resolved during dependency resolution" } }, "required": [ "name", "versionConstraint" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A package dependency with its version constraint" }, - "default": [] + "default": [], + "description": "Dependencies required by this package" }, "depth": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Depth level in the dependency tree (0 = root)" }, "isDirect": { - "type": "boolean" + "type": "boolean", + "description": "Whether this is a direct (top-level) dependency" }, "metadata": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Display name of the package" }, "description": { - "type": "string" + "type": "string", + "description": "Short description of the package" }, "license": { - "type": "string" + "type": "string", + "description": "SPDX license identifier of the package" }, "homepage": { "type": "string", - "format": "uri" + "format": "uri", + "description": "Homepage URL of the package" } }, "required": [ "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Additional metadata about the package" } }, "required": [ @@ -80,7 +94,8 @@ "depth", "isDirect" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A node in the dependency graph representing a resolved package" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/DependencyResolutionResult.json b/packages/spec/json-schema/hub/DependencyResolutionResult.json index 43530340a..4941b4506 100644 --- a/packages/spec/json-schema/hub/DependencyResolutionResult.json +++ b/packages/spec/json-schema/hub/DependencyResolutionResult.json @@ -10,7 +10,8 @@ "success", "conflict", "error" - ] + ], + "description": "Overall status of the dependency resolution" }, "graph": { "type": "object", @@ -19,17 +20,20 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Identifier of the root package" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the root package" } }, "required": [ "id", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Root package of the dependency graph" }, "nodes": { "type": "array", @@ -37,10 +41,12 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the package" }, "version": { - "type": "string" + "type": "string", + "description": "Resolved version of the package" }, "dependencies": { "type": "array", @@ -48,7 +54,8 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Package name or identifier" }, "versionConstraint": { "type": "string", @@ -62,48 +69,59 @@ "peer", "dev" ], - "default": "required" + "default": "required", + "description": "Category of the dependency relationship" }, "resolvedVersion": { - "type": "string" + "type": "string", + "description": "Concrete version resolved during dependency resolution" } }, "required": [ "name", "versionConstraint" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A package dependency with its version constraint" }, - "default": [] + "default": [], + "description": "Dependencies required by this package" }, "depth": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Depth level in the dependency tree (0 = root)" }, "isDirect": { - "type": "boolean" + "type": "boolean", + "description": "Whether this is a direct (top-level) dependency" }, "metadata": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Display name of the package" }, "description": { - "type": "string" + "type": "string", + "description": "Short description of the package" }, "license": { - "type": "string" + "type": "string", + "description": "SPDX license identifier of the package" }, "homepage": { "type": "string", - "format": "uri" + "format": "uri", + "description": "Homepage URL of the package" } }, "required": [ "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Additional metadata about the package" } }, "required": [ @@ -112,8 +130,10 @@ "depth", "isDirect" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "A node in the dependency graph representing a resolved package" + }, + "description": "All resolved package nodes in the dependency graph" }, "edges": { "type": "array", @@ -139,22 +159,26 @@ "constraint" ], "additionalProperties": false - } + }, + "description": "Directed edges representing dependency relationships" }, "stats": { "type": "object", "properties": { "totalDependencies": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Total number of resolved dependencies" }, "directDependencies": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Number of direct (top-level) dependencies" }, "maxDepth": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Maximum depth of the dependency tree" } }, "required": [ @@ -162,7 +186,8 @@ "directDependencies", "maxDepth" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Summary statistics for the dependency graph" } }, "required": [ @@ -171,7 +196,8 @@ "edges", "stats" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Resolved dependency graph if resolution succeeded" }, "conflicts": { "type": "array", @@ -179,7 +205,8 @@ "type": "object", "properties": { "package": { - "type": "string" + "type": "string", + "description": "Name of the package with conflicting version requirements" }, "conflicts": { "type": "array", @@ -187,7 +214,8 @@ "type": "object", "properties": { "version": { - "type": "string" + "type": "string", + "description": "Conflicting version of the package" }, "requestedBy": { "type": "array", @@ -197,7 +225,8 @@ "description": "Packages that require this version" }, "constraint": { - "type": "string" + "type": "string", + "description": "Semver constraint that produced this version requirement" } }, "required": [ @@ -206,7 +235,8 @@ "constraint" ], "additionalProperties": false - } + }, + "description": "List of conflicting version requirements" }, "resolution": { "type": "object", @@ -217,19 +247,23 @@ "pick-highest", "pick-lowest", "manual" - ] + ], + "description": "Strategy used to resolve the conflict" }, "version": { - "type": "string" + "type": "string", + "description": "Resolved version selected by the strategy" }, "reason": { - "type": "string" + "type": "string", + "description": "Explanation of why this resolution was chosen" } }, "required": [ "strategy" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Suggested resolution for the conflict" }, "severity": { "type": "string", @@ -237,7 +271,8 @@ "error", "warning", "info" - ] + ], + "description": "Severity level of the dependency conflict" } }, "required": [ @@ -245,9 +280,11 @@ "conflicts", "severity" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A detected conflict between dependency version requirements" }, - "default": [] + "default": [], + "description": "List of dependency conflicts detected during resolution" }, "errors": { "type": "array", @@ -255,10 +292,12 @@ "type": "object", "properties": { "package": { - "type": "string" + "type": "string", + "description": "Name of the package that caused the error" }, "error": { - "type": "string" + "type": "string", + "description": "Error message describing what went wrong" } }, "required": [ @@ -267,24 +306,28 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "Errors encountered during dependency resolution" }, "installOrder": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "Topologically sorted list of package IDs for installation" }, "resolvedIn": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Time taken to resolve dependencies in milliseconds" } }, "required": [ "status" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Result of a dependency resolution process" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/EdgeLocation.json b/packages/spec/json-schema/hub/EdgeLocation.json index 0a77ec3c3..af8d9b676 100644 --- a/packages/spec/json-schema/hub/EdgeLocation.json +++ b/packages/spec/json-schema/hub/EdgeLocation.json @@ -84,6 +84,11 @@ "inactive" ], "default": "active" + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/hub/FederationTopology.json b/packages/spec/json-schema/hub/FederationTopology.json index cb1b79ab7..aad713e60 100644 --- a/packages/spec/json-schema/hub/FederationTopology.json +++ b/packages/spec/json-schema/hub/FederationTopology.json @@ -179,6 +179,11 @@ } }, "additionalProperties": false + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ @@ -293,6 +298,11 @@ "updatedAt": { "type": "string", "format": "date-time" + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ @@ -395,6 +405,11 @@ "scope" ], "additionalProperties": false + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/hub/HubInstance.json b/packages/spec/json-schema/hub/HubInstance.json index 006f3e877..87a251224 100644 --- a/packages/spec/json-schema/hub/HubInstance.json +++ b/packages/spec/json-schema/hub/HubInstance.json @@ -103,6 +103,11 @@ "updatedAt": { "type": "string", "format": "date-time" + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/hub/PackageDependency.json b/packages/spec/json-schema/hub/PackageDependency.json index 5ecf6aa0e..2537d5d87 100644 --- a/packages/spec/json-schema/hub/PackageDependency.json +++ b/packages/spec/json-schema/hub/PackageDependency.json @@ -5,7 +5,8 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Package name or identifier" }, "versionConstraint": { "type": "string", @@ -19,17 +20,20 @@ "peer", "dev" ], - "default": "required" + "default": "required", + "description": "Category of the dependency relationship" }, "resolvedVersion": { - "type": "string" + "type": "string", + "description": "Concrete version resolved during dependency resolution" } }, "required": [ "name", "versionConstraint" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A package dependency with its version constraint" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/PluginProvenance.json b/packages/spec/json-schema/hub/PluginProvenance.json index a02738ae5..51015b68c 100644 --- a/packages/spec/json-schema/hub/PluginProvenance.json +++ b/packages/spec/json-schema/hub/PluginProvenance.json @@ -5,29 +5,35 @@ "type": "object", "properties": { "pluginId": { - "type": "string" + "type": "string", + "description": "Unique identifier of the plugin" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the plugin artifact" }, "build": { "type": "object", "properties": { "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp when the build was produced" }, "environment": { "type": "object", "properties": { "os": { - "type": "string" + "type": "string", + "description": "Operating system used for the build" }, "arch": { - "type": "string" + "type": "string", + "description": "CPU architecture used for the build" }, "nodeVersion": { - "type": "string" + "type": "string", + "description": "Node.js version used for the build" } }, "required": [ @@ -35,53 +41,63 @@ "arch", "nodeVersion" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Environment details where the build was executed" }, "source": { "type": "object", "properties": { "repository": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the source repository" }, "commit": { "type": "string", - "pattern": "^[a-f0-9]{40}$" + "pattern": "^[a-f0-9]{40}$", + "description": "Full SHA-1 commit hash of the source" }, "branch": { - "type": "string" + "type": "string", + "description": "Branch name the build was produced from" }, "tag": { - "type": "string" + "type": "string", + "description": "Git tag associated with the build" } }, "required": [ "repository", "commit" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Source repository information for the build" }, "builder": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the person or system that produced the build" }, "email": { "type": "string", - "format": "email" + "format": "email", + "description": "Email address of the builder" } }, "required": [ "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Identity of the builder who produced the artifact" } }, "required": [ "timestamp" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Build provenance information" }, "artifacts": { "type": "array", @@ -89,14 +105,17 @@ "type": "object", "properties": { "filename": { - "type": "string" + "type": "string", + "description": "Name of the artifact file" }, "sha256": { - "type": "string" + "type": "string", + "description": "SHA-256 hash of the artifact" }, "size": { "type": "integer", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "description": "Size of the artifact in bytes" } }, "required": [ @@ -105,7 +124,8 @@ "size" ], "additionalProperties": false - } + }, + "description": "List of build artifacts with integrity hashes" }, "signatures": { "type": "array", @@ -118,20 +138,25 @@ "rsa", "ecdsa", "ed25519" - ] + ], + "description": "Cryptographic algorithm used for signing" }, "publicKey": { - "type": "string" + "type": "string", + "description": "Public key used to verify the signature" }, "signature": { - "type": "string" + "type": "string", + "description": "Digital signature value" }, "signedBy": { - "type": "string" + "type": "string", + "description": "Identity of the signer" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp when the signature was created" } }, "required": [ @@ -143,7 +168,8 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "Cryptographic signatures for the plugin artifact" }, "attestations": { "type": "array", @@ -157,22 +183,26 @@ "security-scan", "test-results", "ci-build" - ] + ], + "description": "Type of attestation" }, "status": { "type": "string", "enum": [ "passed", "failed" - ] + ], + "description": "Result status of the attestation" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL with details about the attestation" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp when the attestation was issued" } }, "required": [ @@ -182,7 +212,8 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "Verification attestations for the plugin" } }, "required": [ @@ -191,7 +222,8 @@ "build", "artifacts" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Verifiable provenance and chain of custody for a plugin artifact" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/PluginTrustScore.json b/packages/spec/json-schema/hub/PluginTrustScore.json index a54e0a215..fd150ea08 100644 --- a/packages/spec/json-schema/hub/PluginTrustScore.json +++ b/packages/spec/json-schema/hub/PluginTrustScore.json @@ -5,12 +5,14 @@ "type": "object", "properties": { "pluginId": { - "type": "string" + "type": "string", + "description": "Unique identifier of the plugin" }, "score": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Overall trust score from 0 to 100" }, "components": { "type": "object", @@ -18,27 +20,32 @@ "vendorReputation": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Vendor reputation score from 0 to 100" }, "securityScore": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Security scan results score from 0 to 100" }, "codeQuality": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Code quality score from 0 to 100" }, "communityScore": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Community engagement score from 0 to 100" }, "maintenanceScore": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Maintenance and update frequency score from 0 to 100" } }, "required": [ @@ -48,7 +55,8 @@ "communityScore", "maintenanceScore" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Individual score components contributing to the overall trust score" }, "level": { "type": "string", @@ -58,7 +66,8 @@ "neutral", "untrusted", "blocked" - ] + ], + "description": "Computed trust level based on the overall score" }, "badges": { "type": "array", @@ -73,11 +82,13 @@ "popular" ] }, - "default": [] + "default": [], + "description": "Verification badges earned by the plugin" }, "updatedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp when the trust score was last updated" } }, "required": [ @@ -87,7 +98,8 @@ "level", "updatedAt" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Trust score and verification status for a plugin" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/Region.json b/packages/spec/json-schema/hub/Region.json index c870d360a..f110b41b5 100644 --- a/packages/spec/json-schema/hub/Region.json +++ b/packages/spec/json-schema/hub/Region.json @@ -167,6 +167,11 @@ } }, "additionalProperties": false + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/hub/SBOM.json b/packages/spec/json-schema/hub/SBOM.json index e1d43ca74..2bd8095a9 100644 --- a/packages/spec/json-schema/hub/SBOM.json +++ b/packages/spec/json-schema/hub/SBOM.json @@ -10,22 +10,27 @@ "spdx", "cyclonedx" ], - "default": "cyclonedx" + "default": "cyclonedx", + "description": "SBOM standard format used" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the SBOM specification" }, "plugin": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Plugin identifier" }, "version": { - "type": "string" + "type": "string", + "description": "Plugin version" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable plugin name" } }, "required": [ @@ -33,7 +38,8 @@ "version", "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Metadata about the plugin this SBOM describes" }, "components": { "type": "array", @@ -41,45 +47,54 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the software component" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the software component" }, "purl": { "type": "string", "description": "Package URL identifier" }, "license": { - "type": "string" + "type": "string", + "description": "SPDX license identifier of the component" }, "hashes": { "type": "object", "properties": { "sha256": { - "type": "string" + "type": "string", + "description": "SHA-256 hash of the component artifact" }, "sha512": { - "type": "string" + "type": "string", + "description": "SHA-512 hash of the component artifact" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Cryptographic hashes for integrity verification" }, "supplier": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the component supplier" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the component supplier" } }, "required": [ "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Supplier information for the component" }, "externalRefs": { "type": "array", @@ -93,11 +108,13 @@ "repository", "documentation", "issue-tracker" - ] + ], + "description": "Type of external reference" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the external reference" } }, "required": [ @@ -106,35 +123,42 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "External references related to the component" } }, "required": [ "name", "version" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "A single entry in a Software Bill of Materials" + }, + "description": "List of software components included in the plugin" }, "generatedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp when the SBOM was generated" }, "generator": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the SBOM generator tool" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the SBOM generator tool" } }, "required": [ "name", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Tool used to generate this SBOM" } }, "required": [ @@ -143,7 +167,8 @@ "components", "generatedAt" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Software Bill of Materials for a plugin" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/SBOMEntry.json b/packages/spec/json-schema/hub/SBOMEntry.json index 8bfe3b77a..27726f8ad 100644 --- a/packages/spec/json-schema/hub/SBOMEntry.json +++ b/packages/spec/json-schema/hub/SBOMEntry.json @@ -5,45 +5,54 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the software component" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the software component" }, "purl": { "type": "string", "description": "Package URL identifier" }, "license": { - "type": "string" + "type": "string", + "description": "SPDX license identifier of the component" }, "hashes": { "type": "object", "properties": { "sha256": { - "type": "string" + "type": "string", + "description": "SHA-256 hash of the component artifact" }, "sha512": { - "type": "string" + "type": "string", + "description": "SHA-512 hash of the component artifact" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Cryptographic hashes for integrity verification" }, "supplier": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the component supplier" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the component supplier" } }, "required": [ "name" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Supplier information for the component" }, "externalRefs": { "type": "array", @@ -57,11 +66,13 @@ "repository", "documentation", "issue-tracker" - ] + ], + "description": "Type of external reference" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the external reference" } }, "required": [ @@ -70,14 +81,16 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "External references related to the component" } }, "required": [ "name", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A single entry in a Software Bill of Materials" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/SecurityPolicy.json b/packages/spec/json-schema/hub/SecurityPolicy.json index d511e762d..63039fe35 100644 --- a/packages/spec/json-schema/hub/SecurityPolicy.json +++ b/packages/spec/json-schema/hub/SecurityPolicy.json @@ -5,17 +5,20 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the security policy" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name of the security policy" }, "autoScan": { "type": "object", "properties": { "enabled": { "type": "boolean", - "default": true + "default": true, + "description": "Whether automatic scanning is enabled" }, "frequency": { "type": "string", @@ -25,10 +28,12 @@ "weekly", "monthly" ], - "default": "daily" + "default": "daily", + "description": "How often automatic scans are performed" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Automatic security scanning configuration" }, "thresholds": { "type": "object", @@ -36,20 +41,24 @@ "maxCritical": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Maximum allowed critical vulnerabilities before blocking" }, "maxHigh": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Maximum allowed high vulnerabilities before blocking" }, "maxMedium": { "type": "integer", "minimum": 0, - "default": 5 + "default": 5, + "description": "Maximum allowed medium vulnerabilities before warning" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Vulnerability count thresholds for policy enforcement" }, "allowedLicenses": { "type": "array", @@ -62,7 +71,8 @@ "BSD-3-Clause", "BSD-2-Clause", "ISC" - ] + ], + "description": "List of SPDX license identifiers that are permitted" }, "prohibitedLicenses": { "type": "array", @@ -72,24 +82,28 @@ "default": [ "GPL-3.0", "AGPL-3.0" - ] + ], + "description": "List of SPDX license identifiers that are prohibited" }, "codeSigning": { "type": "object", "properties": { "required": { "type": "boolean", - "default": false + "default": false, + "description": "Whether code signing is required for plugins" }, "allowedSigners": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "List of trusted signer identities" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Code signing requirements for plugin artifacts" }, "sandbox": { "type": "object", @@ -102,14 +116,16 @@ "allowlist", "all" ], - "default": "all" + "default": "all", + "description": "Level of network access granted to the plugin" }, "allowedDestinations": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "Permitted network destinations when using allowlist mode" }, "filesystemAccess": { "type": "string", @@ -119,18 +135,22 @@ "temp-only", "full" ], - "default": "full" + "default": "full", + "description": "Level of file system access granted to the plugin" }, "maxMemoryMB": { "type": "integer", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "description": "Maximum memory allocation in megabytes" }, "maxCPUSeconds": { "type": "integer", - "exclusiveMinimum": 0 + "exclusiveMinimum": 0, + "description": "Maximum CPU time allowed in seconds" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Sandbox restrictions for plugin execution" } }, "required": [ @@ -139,7 +159,8 @@ "autoScan", "thresholds" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Security policy governing plugin scanning and enforcement" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/SecurityScanResult.json b/packages/spec/json-schema/hub/SecurityScanResult.json index a3a5dbc99..22f096c17 100644 --- a/packages/spec/json-schema/hub/SecurityScanResult.json +++ b/packages/spec/json-schema/hub/SecurityScanResult.json @@ -6,27 +6,32 @@ "properties": { "scanId": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "Unique identifier for this security scan" }, "plugin": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Plugin identifier" }, "version": { - "type": "string" + "type": "string", + "description": "Plugin version that was scanned" } }, "required": [ "id", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Plugin that was scanned" }, "scannedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp when the scan was performed" }, "scanner": { "type": "object", @@ -36,14 +41,16 @@ "description": "Scanner name (e.g., snyk, osv, trivy)" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the scanner tool" } }, "required": [ "name", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Information about the scanner tool used" }, "status": { "type": "string", @@ -51,7 +58,8 @@ "passed", "failed", "warning" - ] + ], + "description": "Overall result status of the security scan" }, "vulnerabilities": { "type": "array", @@ -68,10 +76,12 @@ "description": "Vulnerability ID" }, "title": { - "type": "string" + "type": "string", + "description": "Short title summarizing the vulnerability" }, "description": { - "type": "string" + "type": "string", + "description": "Detailed description of the vulnerability" }, "severity": { "type": "string", @@ -81,31 +91,37 @@ "medium", "low", "info" - ] + ], + "description": "Severity level of this vulnerability" }, "cvss": { "type": "number", "minimum": 0, - "maximum": 10 + "maximum": 10, + "description": "CVSS score ranging from 0 to 10" }, "package": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the affected package" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the affected package" }, "ecosystem": { - "type": "string" + "type": "string", + "description": "Package ecosystem (e.g., npm, pip, maven)" } }, "required": [ "name", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Affected package information" }, "vulnerableVersions": { "type": "string", @@ -127,11 +143,13 @@ "article", "report", "web" - ] + ], + "description": "Type of reference source" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the reference" } }, "required": [ @@ -140,21 +158,25 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "External references related to the vulnerability" }, "cwe": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "CWE identifiers associated with this vulnerability" }, "publishedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 date when the vulnerability was published" }, "mitigation": { - "type": "string" + "type": "string", + "description": "Recommended steps to mitigate the vulnerability" } }, "required": [ @@ -165,8 +187,10 @@ "package", "vulnerableVersions" ], - "additionalProperties": false - } + "additionalProperties": false, + "description": "A known security vulnerability in a package dependency" + }, + "description": "List of vulnerabilities discovered during the scan" }, "summary": { "type": "object", @@ -174,35 +198,42 @@ "critical": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Count of critical severity vulnerabilities" }, "high": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Count of high severity vulnerabilities" }, "medium": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Count of medium severity vulnerabilities" }, "low": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Count of low severity vulnerabilities" }, "info": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Count of informational severity vulnerabilities" }, "total": { "type": "integer", "minimum": 0, - "default": 0 + "default": 0, + "description": "Total count of all vulnerabilities" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Summary counts of vulnerabilities by severity" }, "licenseIssues": { "type": "array", @@ -210,13 +241,16 @@ "type": "object", "properties": { "package": { - "type": "string" + "type": "string", + "description": "Name of the package with a license issue" }, "license": { - "type": "string" + "type": "string", + "description": "License identifier of the package" }, "reason": { - "type": "string" + "type": "string", + "description": "Reason the license is flagged" }, "severity": { "type": "string", @@ -224,7 +258,8 @@ "error", "warning", "info" - ] + ], + "description": "Severity of the license compliance issue" } }, "required": [ @@ -235,7 +270,8 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "License compliance issues found during the scan" }, "codeQuality": { "type": "object", @@ -243,7 +279,8 @@ "score": { "type": "number", "minimum": 0, - "maximum": 100 + "maximum": 100, + "description": "Overall code quality score from 0 to 100" }, "issues": { "type": "array", @@ -256,7 +293,8 @@ "security", "quality", "style" - ] + ], + "description": "Category of the code quality issue" }, "severity": { "type": "string", @@ -264,16 +302,20 @@ "error", "warning", "info" - ] + ], + "description": "Severity of the code quality issue" }, "message": { - "type": "string" + "type": "string", + "description": "Description of the code quality issue" }, "file": { - "type": "string" + "type": "string", + "description": "File path where the issue was found" }, "line": { - "type": "integer" + "type": "integer", + "description": "Line number where the issue was found" } }, "required": [ @@ -283,14 +325,17 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "List of individual code quality issues" } }, - "additionalProperties": false + "additionalProperties": false, + "description": "Code quality analysis results" }, "nextScanAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 timestamp for the next scheduled scan" } }, "required": [ @@ -302,7 +347,8 @@ "vulnerabilities", "summary" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Result of a security scan performed on a plugin" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/SecurityVulnerability.json b/packages/spec/json-schema/hub/SecurityVulnerability.json index 3f3c08c0e..c14b17293 100644 --- a/packages/spec/json-schema/hub/SecurityVulnerability.json +++ b/packages/spec/json-schema/hub/SecurityVulnerability.json @@ -14,10 +14,12 @@ "description": "Vulnerability ID" }, "title": { - "type": "string" + "type": "string", + "description": "Short title summarizing the vulnerability" }, "description": { - "type": "string" + "type": "string", + "description": "Detailed description of the vulnerability" }, "severity": { "type": "string", @@ -27,31 +29,37 @@ "medium", "low", "info" - ] + ], + "description": "Severity level of this vulnerability" }, "cvss": { "type": "number", "minimum": 0, - "maximum": 10 + "maximum": 10, + "description": "CVSS score ranging from 0 to 10" }, "package": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the affected package" }, "version": { - "type": "string" + "type": "string", + "description": "Version of the affected package" }, "ecosystem": { - "type": "string" + "type": "string", + "description": "Package ecosystem (e.g., npm, pip, maven)" } }, "required": [ "name", "version" ], - "additionalProperties": false + "additionalProperties": false, + "description": "Affected package information" }, "vulnerableVersions": { "type": "string", @@ -73,11 +81,13 @@ "article", "report", "web" - ] + ], + "description": "Type of reference source" }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "URL of the reference" } }, "required": [ @@ -86,21 +96,25 @@ ], "additionalProperties": false }, - "default": [] + "default": [], + "description": "External references related to the vulnerability" }, "cwe": { "type": "array", "items": { "type": "string" }, - "default": [] + "default": [], + "description": "CWE identifiers associated with this vulnerability" }, "publishedAt": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "ISO 8601 date when the vulnerability was published" }, "mitigation": { - "type": "string" + "type": "string", + "description": "Recommended steps to mitigate the vulnerability" } }, "required": [ @@ -111,7 +125,8 @@ "package", "vulnerableVersions" ], - "additionalProperties": false + "additionalProperties": false, + "description": "A known security vulnerability in a package dependency" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/hub/VulnerabilitySeverity.json b/packages/spec/json-schema/hub/VulnerabilitySeverity.json index 07a8d071f..bbeaba738 100644 --- a/packages/spec/json-schema/hub/VulnerabilitySeverity.json +++ b/packages/spec/json-schema/hub/VulnerabilitySeverity.json @@ -9,7 +9,8 @@ "medium", "low", "info" - ] + ], + "description": "Severity level of a security vulnerability" } }, "$schema": "http://json-schema.org/draft-07/schema#" diff --git a/packages/spec/json-schema/kernel/OpsDomainModule.json b/packages/spec/json-schema/kernel/OpsDomainModule.json index 71d251085..c6b92161b 100644 --- a/packages/spec/json-schema/kernel/OpsDomainModule.json +++ b/packages/spec/json-schema/kernel/OpsDomainModule.json @@ -15,6 +15,11 @@ "type": "string" }, "description": "List of files in this module" + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/kernel/OpsPluginStructure.json b/packages/spec/json-schema/kernel/OpsPluginStructure.json index 1c62d8060..ade5888df 100644 --- a/packages/spec/json-schema/kernel/OpsPluginStructure.json +++ b/packages/spec/json-schema/kernel/OpsPluginStructure.json @@ -14,6 +14,11 @@ "type": "string" }, "description": "List of all file paths relative to root" + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/json-schema/system/ChangeRequest.json b/packages/spec/json-schema/system/ChangeRequest.json index 23bcfd1fc..64da5c05f 100644 --- a/packages/spec/json-schema/system/ChangeRequest.json +++ b/packages/spec/json-schema/system/ChangeRequest.json @@ -291,6 +291,11 @@ "additionalProperties": false }, "description": "Attachments" + }, + "metadata": { + "type": "object", + "additionalProperties": {}, + "description": "Custom metadata key-value pairs for extensibility" } }, "required": [ diff --git a/packages/spec/src/api/discovery.zod.ts b/packages/spec/src/api/discovery.zod.ts index b1497c11f..e065564f2 100644 --- a/packages/spec/src/api/discovery.zod.ts +++ b/packages/spec/src/api/discovery.zod.ts @@ -69,6 +69,11 @@ export const DiscoverySchema = z.object({ supported: z.array(z.string()), timezone: z.string(), }), + + /** + * Custom metadata key-value pairs for extensibility + */ + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }); export type DiscoveryResponse = z.infer; diff --git a/packages/spec/src/api/hub.zod.ts b/packages/spec/src/api/hub.zod.ts index 8b583e2fa..9b88a65cb 100644 --- a/packages/spec/src/api/hub.zod.ts +++ b/packages/spec/src/api/hub.zod.ts @@ -39,23 +39,23 @@ export const PaginationRequestSchema = z.object({ /** * Page number (1-indexed) */ - page: z.number().int().min(1).default(1).optional(), + page: z.number().int().min(1).default(1).optional().describe('Page number (1-indexed)'), /** * Number of items per page */ - perPage: z.number().int().min(1).max(100).default(20).optional(), + perPage: z.number().int().min(1).max(100).default(20).optional().describe('Number of items per page'), /** * Sort field */ - sortBy: z.string().optional(), + sortBy: z.string().optional().describe('Field name to sort results by'), /** * Sort direction */ - sortOrder: z.enum(['asc', 'desc']).default('desc').optional(), -}); + sortOrder: z.enum(['asc', 'desc']).default('desc').optional().describe('Sort direction'), +}).describe('Pagination request parameters'); /** * Pagination Response Metadata @@ -64,33 +64,33 @@ export const PaginationResponseSchema = z.object({ /** * Current page number */ - page: z.number().int().min(1), + page: z.number().int().min(1).describe('Current page number'), /** * Items per page */ - perPage: z.number().int().min(1), + perPage: z.number().int().min(1).describe('Items per page'), /** * Total number of items */ - total: z.number().int().min(0), + total: z.number().int().min(0).describe('Total number of items'), /** * Total number of pages */ - totalPages: z.number().int().min(0), + totalPages: z.number().int().min(0).describe('Total number of pages'), /** * Whether there is a next page */ - hasNext: z.boolean(), + hasNext: z.boolean().describe('Whether there is a next page'), /** * Whether there is a previous page */ - hasPrev: z.boolean(), -}); + hasPrev: z.boolean().describe('Whether there is a previous page'), +}).describe('Pagination response metadata'); // ============================================================================ // Space Management API @@ -120,11 +120,11 @@ export const CreateSpaceRequestSchema = z.object({ name: z.string().min(1).max(255).describe('Space display name'), slug: z.string().regex(/^[a-z0-9-]+$/).min(1).max(100).describe('URL-friendly identifier'), ownerId: z.string().describe('Owner user/org ID'), - runtime: HubSpaceSchema.shape.runtime.optional(), + runtime: HubSpaceSchema.shape.runtime.optional().describe('Runtime configuration for the space'), bom: BillOfMaterialsSchema.optional().describe('Initial Bill of Materials'), - subscription: HubSpaceSchema.shape.subscription.optional(), - deployment: HubSpaceSchema.shape.deployment.optional(), -}); + subscription: HubSpaceSchema.shape.subscription.optional().describe('Subscription plan configuration'), + deployment: HubSpaceSchema.shape.deployment.optional().describe('Deployment settings for the space'), +}).describe('Request payload for creating a new space'); /** * Update Space Request @@ -143,7 +143,7 @@ export const CreateSpaceRequestSchema = z.object({ * } * ``` */ -export const UpdateSpaceRequestSchema = CreateSpaceRequestSchema.partial(); +export const UpdateSpaceRequestSchema = CreateSpaceRequestSchema.partial().describe('Request payload for updating an existing space'); /** * Space Response @@ -174,8 +174,8 @@ export const UpdateSpaceRequestSchema = CreateSpaceRequestSchema.partial(); * ``` */ export const SpaceResponseSchema = BaseResponseSchema.extend({ - data: HubSpaceSchema -}); + data: HubSpaceSchema.describe('Space details'), +}).describe('Response containing a single space'); /** * List Spaces Request @@ -183,7 +183,7 @@ export const SpaceResponseSchema = BaseResponseSchema.extend({ export const ListSpacesRequestSchema = PaginationRequestSchema.extend({ ownerId: z.string().optional().describe('Filter by owner'), search: z.string().optional().describe('Search in name and slug'), -}); +}).describe('Request parameters for listing spaces'); /** * List Spaces Response @@ -214,9 +214,9 @@ export const ListSpacesRequestSchema = PaginationRequestSchema.extend({ * ``` */ export const ListSpacesResponseSchema = BaseResponseSchema.extend({ - data: z.array(HubSpaceSchema), - pagination: PaginationResponseSchema, -}); + data: z.array(HubSpaceSchema).describe('List of spaces'), + pagination: PaginationResponseSchema.describe('Pagination metadata'), +}).describe('Paginated response containing a list of spaces'); // ============================================================================ // Tenant Management API @@ -240,38 +240,38 @@ export const ListSpacesResponseSchema = BaseResponseSchema.extend({ */ export const CreateTenantRequestSchema = z.object({ name: z.string().min(1).max(255).describe('Tenant display name'), - isolationLevel: TenantSchema.shape.isolationLevel, - customizations: TenantSchema.shape.customizations.optional(), - quotas: TenantSchema.shape.quotas.optional(), -}); + isolationLevel: TenantSchema.shape.isolationLevel.describe('Data isolation level for the tenant'), + customizations: TenantSchema.shape.customizations.optional().describe('Tenant-specific customizations'), + quotas: TenantSchema.shape.quotas.optional().describe('Resource quotas for the tenant'), +}).describe('Request payload for creating a new tenant'); /** * Update Tenant Request */ -export const UpdateTenantRequestSchema = CreateTenantRequestSchema.partial(); +export const UpdateTenantRequestSchema = CreateTenantRequestSchema.partial().describe('Request payload for updating an existing tenant'); /** * Tenant Response */ export const TenantResponseSchema = BaseResponseSchema.extend({ - data: TenantSchema -}); + data: TenantSchema.describe('Tenant details'), +}).describe('Response containing a single tenant'); /** * List Tenants Request */ export const ListTenantsRequestSchema = PaginationRequestSchema.extend({ - isolationLevel: TenantSchema.shape.isolationLevel.optional(), - search: z.string().optional(), -}); + isolationLevel: TenantSchema.shape.isolationLevel.optional().describe('Filter by isolation level'), + search: z.string().optional().describe('Search tenants by name'), +}).describe('Request parameters for listing tenants'); /** * List Tenants Response */ export const ListTenantsResponseSchema = BaseResponseSchema.extend({ - data: z.array(TenantSchema), - pagination: PaginationResponseSchema, -}); + data: z.array(TenantSchema).describe('List of tenants'), + pagination: PaginationResponseSchema.describe('Pagination metadata'), +}).describe('Paginated response containing a list of tenants'); // ============================================================================ // Plugin Registry API @@ -302,19 +302,19 @@ export const PublishPluginRequestSchema = PluginRegistryEntrySchema.omit({ updatedAt: true, statistics: true, quality: true, -}); +}).describe('Request payload for publishing a plugin'); /** * Update Plugin Request */ -export const UpdatePluginRequestSchema = PublishPluginRequestSchema.partial(); +export const UpdatePluginRequestSchema = PublishPluginRequestSchema.partial().describe('Request payload for updating a published plugin'); /** * Plugin Response */ export const PluginResponseSchema = BaseResponseSchema.extend({ - data: PluginRegistryEntrySchema -}); + data: PluginRegistryEntrySchema.describe('Plugin registry entry details'), +}).describe('Response containing a single plugin'); /** * Search Plugins Request @@ -362,39 +362,39 @@ export const SearchPluginsRequestSchema = PluginSearchFiltersSchema; * ``` */ export const SearchPluginsResponseSchema = BaseResponseSchema.extend({ - data: z.array(PluginRegistryEntrySchema), - pagination: PaginationResponseSchema, -}); + data: z.array(PluginRegistryEntrySchema).describe('List of matching plugins'), + pagination: PaginationResponseSchema.describe('Pagination metadata'), +}).describe('Paginated response containing plugin search results'); /** * Get Plugin Versions Request */ export const GetPluginVersionsRequestSchema = z.object({ pluginId: z.string().describe('Plugin identifier'), -}); +}).describe('Request parameters for retrieving plugin versions'); /** * Plugin Version Info */ export const PluginVersionInfoSchema = z.object({ - version: z.string(), - publishedAt: z.string().datetime(), - deprecated: z.boolean().default(false), + version: z.string().describe('Semantic version string'), + publishedAt: z.string().datetime().describe('Timestamp when this version was published'), + deprecated: z.boolean().default(false).describe('Whether this version is deprecated'), yanked: z.boolean().default(false).describe('Whether this version was removed'), - changelog: z.string().optional(), -}); + changelog: z.string().optional().describe('Release notes for this version'), +}).describe('Version metadata for a plugin release'); /** * Get Plugin Versions Response */ export const GetPluginVersionsResponseSchema = BaseResponseSchema.extend({ data: z.object({ - pluginId: z.string(), - versions: z.array(PluginVersionInfoSchema), + pluginId: z.string().describe('Plugin identifier'), + versions: z.array(PluginVersionInfoSchema).describe('List of available versions'), latest: z.string().describe('Latest stable version'), latestPrerelease: z.string().optional().describe('Latest pre-release version'), - }) -}); + }).describe('Plugin version listing'), +}).describe('Response containing plugin version information'); // ============================================================================ // Marketplace API @@ -404,38 +404,38 @@ export const GetPluginVersionsResponseSchema = BaseResponseSchema.extend({ * List Marketplace Plugins Request */ export const ListMarketplaceRequestSchema = PaginationRequestSchema.extend({ - category: z.string().optional(), - tags: z.array(z.string()).optional(), - verified: z.boolean().optional(), - search: z.string().optional(), -}); + category: z.string().optional().describe('Filter by plugin category'), + tags: z.array(z.string()).optional().describe('Filter by tags'), + verified: z.boolean().optional().describe('Filter by vendor verification status'), + search: z.string().optional().describe('Search marketplace plugins by keyword'), +}).describe('Request parameters for listing marketplace plugins'); /** * List Marketplace Response */ export const ListMarketplaceResponseSchema = BaseResponseSchema.extend({ - data: z.array(MarketplacePluginSchema), - pagination: PaginationResponseSchema, + data: z.array(MarketplacePluginSchema).describe('List of marketplace plugins'), + pagination: PaginationResponseSchema.describe('Pagination metadata'), categories: z.array(z.object({ - id: z.string(), - label: z.string(), - count: z.number().int(), - })).optional().describe('Available categories with counts'), -}); + id: z.string().describe('Category identifier'), + label: z.string().describe('Category display name'), + count: z.number().int().describe('Number of plugins in this category'), + }).describe('Marketplace category summary')).optional().describe('Available categories with counts'), +}).describe('Paginated response containing marketplace plugin listings'); /** * Get Marketplace Plugin Details Request */ export const GetMarketplacePluginRequestSchema = z.object({ - pluginId: z.string(), -}); + pluginId: z.string().describe('Plugin identifier to retrieve'), +}).describe('Request parameters for retrieving marketplace plugin details'); /** * Marketplace Plugin Details Response */ export const MarketplacePluginResponseSchema = BaseResponseSchema.extend({ - data: MarketplacePluginSchema -}); + data: MarketplacePluginSchema.describe('Marketplace plugin details'), +}).describe('Response containing marketplace plugin details'); // ============================================================================ // License Management API @@ -462,18 +462,18 @@ export const MarketplacePluginResponseSchema = BaseResponseSchema.extend({ export const IssueLicenseRequestSchema = z.object({ spaceId: z.string().describe('Target space ID'), planCode: z.string().describe('Plan code'), - expiresAt: z.string().datetime().optional(), - customFeatures: z.array(z.string()).optional(), - customLimits: z.record(z.string(), z.number()).optional(), - plugins: z.array(z.string()).optional(), -}); + expiresAt: z.string().datetime().optional().describe('License expiration date'), + customFeatures: z.array(z.string()).optional().describe('Custom feature flags to enable'), + customLimits: z.record(z.string(), z.number()).optional().describe('Custom resource limits'), + plugins: z.array(z.string()).optional().describe('Licensed plugin identifiers'), +}).describe('Request payload for issuing a new license'); /** * License Response */ export const LicenseResponseSchema = BaseResponseSchema.extend({ - data: LicenseSchema -}); + data: LicenseSchema.describe('License details'), +}).describe('Response containing a single license'); /** * Validate License Request @@ -487,9 +487,9 @@ export const LicenseResponseSchema = BaseResponseSchema.extend({ * ``` */ export const ValidateLicenseRequestSchema = z.object({ - spaceId: z.string(), + spaceId: z.string().describe('Space ID to validate the license for'), signature: z.string().describe('License signature/token'), -}); +}).describe('Request payload for validating a license'); /** * License Validation Response @@ -514,37 +514,37 @@ export const ValidateLicenseRequestSchema = z.object({ */ export const ValidateLicenseResponseSchema = BaseResponseSchema.extend({ data: z.object({ - valid: z.boolean(), - license: LicenseSchema.optional(), - errors: z.array(z.string()).default([]), - warnings: z.array(z.string()).default([]), - }) -}); + valid: z.boolean().describe('Whether the license is valid'), + license: LicenseSchema.optional().describe('License details if found'), + errors: z.array(z.string()).default([]).describe('Validation error messages'), + warnings: z.array(z.string()).default([]).describe('Validation warning messages'), + }).describe('License validation result'), +}).describe('Response containing license validation results'); /** * Revoke License Request */ export const RevokeLicenseRequestSchema = z.object({ - spaceId: z.string(), - reason: z.string().optional(), -}); + spaceId: z.string().describe('Space ID whose license should be revoked'), + reason: z.string().optional().describe('Reason for revoking the license'), +}).describe('Request payload for revoking a license'); /** * List Licenses Request */ export const ListLicensesRequestSchema = PaginationRequestSchema.extend({ - spaceId: z.string().optional(), - planCode: z.string().optional(), - status: LicenseSchema.shape.status.optional(), -}); + spaceId: z.string().optional().describe('Filter by space ID'), + planCode: z.string().optional().describe('Filter by plan code'), + status: LicenseSchema.shape.status.optional().describe('Filter by license status'), +}).describe('Request parameters for listing licenses'); /** * List Licenses Response */ export const ListLicensesResponseSchema = BaseResponseSchema.extend({ - data: z.array(LicenseSchema), - pagination: PaginationResponseSchema, -}); + data: z.array(LicenseSchema).describe('List of licenses'), + pagination: PaginationResponseSchema.describe('Pagination metadata'), +}).describe('Paginated response containing a list of licenses'); // ============================================================================ // Composer Service API @@ -581,15 +581,15 @@ export const CompileManifestRequestSchema = ComposerRequestSchema; * Compile Manifest Response */ export const CompileManifestResponseSchema = BaseResponseSchema.extend({ - data: ComposerResponseSchema -}); + data: ComposerResponseSchema.describe('Compilation result'), +}).describe('Response containing the compiled manifest result'); /** * Get Build Status Request */ export const GetBuildStatusRequestSchema = z.object({ - buildId: z.string(), -}); + buildId: z.string().describe('Unique build identifier'), +}).describe('Request parameters for retrieving build status'); /** * Build Status Response @@ -615,20 +615,20 @@ export const GetBuildStatusRequestSchema = z.object({ */ export const BuildStatusResponseSchema = BaseResponseSchema.extend({ data: z.object({ - buildId: z.string(), - status: z.enum(['pending', 'in_progress', 'success', 'failed']), + buildId: z.string().describe('Unique build identifier'), + status: z.enum(['pending', 'in_progress', 'success', 'failed']).describe('Current build status'), progress: z.number().min(0).max(100).describe('Completion percentage'), - startedAt: z.string().datetime().optional(), - completedAt: z.string().datetime().optional(), + startedAt: z.string().datetime().optional().describe('Timestamp when the build started'), + completedAt: z.string().datetime().optional().describe('Timestamp when the build completed'), duration: z.number().optional().describe('Duration in milliseconds'), logs: z.array(z.object({ - timestamp: z.string().datetime(), - level: z.enum(['debug', 'info', 'warn', 'error']), - message: z.string(), - })).optional(), - error: z.string().optional(), - }) -}); + timestamp: z.string().datetime().describe('Log entry timestamp'), + level: z.enum(['debug', 'info', 'warn', 'error']).describe('Log severity level'), + message: z.string().describe('Log message content'), + }).describe('Build log entry')).optional().describe('Build log entries'), + error: z.string().optional().describe('Error message if the build failed'), + }).describe('Build status details'), +}).describe('Response containing build status information'); // ============================================================================ // Health & Monitoring @@ -666,17 +666,17 @@ export const BuildStatusResponseSchema = BaseResponseSchema.extend({ */ export const HubHealthResponseSchema = BaseResponseSchema.extend({ data: z.object({ - status: z.enum(['healthy', 'degraded', 'unhealthy']), - version: z.string(), + status: z.enum(['healthy', 'degraded', 'unhealthy']).describe('Overall hub health status'), + version: z.string().describe('Hub service version'), uptime: z.number().describe('Uptime in seconds'), services: z.record(z.string(), z.object({ - status: z.enum(['healthy', 'degraded', 'unhealthy']), + status: z.enum(['healthy', 'degraded', 'unhealthy']).describe('Service health status'), latency: z.number().optional().describe('Latency in milliseconds'), - message: z.string().optional(), - })), - timestamp: z.string().datetime(), - }) -}); + message: z.string().optional().describe('Additional status message'), + }).describe('Individual service health details')).describe('Health status of dependent services'), + timestamp: z.string().datetime().describe('Timestamp of the health check'), + }).describe('Hub health check details'), +}).describe('Response containing hub health status'); /** * Hub Metrics Response @@ -716,28 +716,28 @@ export const HubMetricsResponseSchema = BaseResponseSchema.extend({ data: z.object({ metrics: z.object({ spaces: z.object({ - total: z.number().int(), - active: z.number().int(), - created_last_30d: z.number().int().optional(), - }).optional(), + total: z.number().int().describe('Total number of spaces'), + active: z.number().int().describe('Number of active spaces'), + created_last_30d: z.number().int().optional().describe('Spaces created in the last 30 days'), + }).optional().describe('Space-related metrics'), tenants: z.object({ - total: z.number().int(), - active: z.number().int(), - }).optional(), + total: z.number().int().describe('Total number of tenants'), + active: z.number().int().describe('Number of active tenants'), + }).optional().describe('Tenant-related metrics'), plugins: z.object({ - total: z.number().int(), - published_last_30d: z.number().int().optional(), - total_downloads: z.number().int().optional(), - }).optional(), + total: z.number().int().describe('Total number of plugins'), + published_last_30d: z.number().int().optional().describe('Plugins published in the last 30 days'), + total_downloads: z.number().int().optional().describe('Cumulative plugin downloads'), + }).optional().describe('Plugin-related metrics'), api: z.object({ - requests_per_minute: z.number(), + requests_per_minute: z.number().describe('Current API request rate per minute'), avg_response_time: z.number().describe('Milliseconds'), - error_rate: z.number().min(0).max(1), - }).optional(), - }), - timestamp: z.string().datetime(), - }) -}); + error_rate: z.number().min(0).max(1).describe('Ratio of failed API requests'), + }).optional().describe('API performance metrics'), + }).describe('Aggregated hub metrics'), + timestamp: z.string().datetime().describe('Timestamp when metrics were collected'), + }).describe('Hub metrics data'), +}).describe('Response containing hub operational metrics'); // ============================================================================ // Export Types @@ -824,7 +824,7 @@ export const HubAPIContract = { response: ListSpacesResponseSchema, }, delete: { - response: z.object({ success: z.boolean() }), + response: z.object({ success: z.boolean().describe('Whether the deletion was successful') }).describe('Space deletion response'), }, }, @@ -846,7 +846,7 @@ export const HubAPIContract = { response: ListTenantsResponseSchema, }, delete: { - response: z.object({ success: z.boolean() }), + response: z.object({ success: z.boolean().describe('Whether the deletion was successful') }).describe('Tenant deletion response'), }, }, @@ -872,7 +872,7 @@ export const HubAPIContract = { response: GetPluginVersionsResponseSchema, }, delete: { - response: z.object({ success: z.boolean() }), + response: z.object({ success: z.boolean().describe('Whether the deletion was successful') }).describe('Plugin deletion response'), }, }, @@ -900,7 +900,7 @@ export const HubAPIContract = { }, revoke: { request: RevokeLicenseRequestSchema, - response: z.object({ success: z.boolean() }), + response: z.object({ success: z.boolean().describe('Whether the revocation was successful') }).describe('License revocation response'), }, list: { request: ListLicensesRequestSchema, @@ -939,14 +939,14 @@ export const InstallPluginRequestSchema = z.object({ pluginId: z.string().describe('Plugin Package ID'), version: z.string().optional().describe('Version requirement'), config: z.record(z.string(), z.unknown()).optional().describe('Plugin configuration'), -}); +}).describe('Request payload for installing a plugin into a space'); /** * Install Plugin Response */ export const InstallPluginResponseSchema = BaseResponseSchema.extend({ - data: z.unknown() // Returns installation status or installed instance -}); + data: z.unknown().describe('Installation status or installed plugin instance'), +}).describe('Response containing plugin installation result'); diff --git a/packages/spec/src/data/analytics.zod.ts b/packages/spec/src/data/analytics.zod.ts index 212eb1404..f5cf41098 100644 --- a/packages/spec/src/data/analytics.zod.ts +++ b/packages/spec/src/data/analytics.zod.ts @@ -11,10 +11,10 @@ import { z } from 'zod'; */ /** - * Metric Type - * The mathematical operation to perform. + * Aggregation Metric Type + * The mathematical operation to perform on a metric. */ -export const MetricType = z.enum([ +export const AggregationMetricType = z.enum([ 'count', 'sum', 'avg', @@ -54,7 +54,7 @@ export const MetricSchema = z.object({ label: z.string().describe('Human readable label'), description: z.string().optional(), - type: MetricType, + type: AggregationMetricType, /** Source Calculation */ sql: z.string().describe('SQL expression or field reference'), diff --git a/packages/spec/src/hub/hub-federation.zod.ts b/packages/spec/src/hub/hub-federation.zod.ts index 7d9ce0019..c403a8e6d 100644 --- a/packages/spec/src/hub/hub-federation.zod.ts +++ b/packages/spec/src/hub/hub-federation.zod.ts @@ -83,6 +83,11 @@ export const RegionSchema = z.object({ maxTenants: z.number().int().positive().optional(), maxStorage: z.number().int().positive().optional().describe('Bytes'), }).optional(), + + /** + * Custom metadata key-value pairs for extensibility + */ + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }); export type Region = z.infer; @@ -159,6 +164,11 @@ export const HubInstanceSchema = z.object({ */ createdAt: z.string().datetime(), updatedAt: z.string().datetime(), + + /** + * Custom metadata key-value pairs for extensibility + */ + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }); export type HubInstance = z.infer; @@ -255,6 +265,11 @@ export const FederationTopologySchema = z.object({ */ conflictResolution: z.enum(['last-write-wins', 'primary-wins', 'manual']).default('last-write-wins'), }), + + /** + * Custom metadata key-value pairs for extensibility + */ + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }); export type FederationTopology = z.infer; @@ -503,6 +518,11 @@ export const EdgeLocationSchema = z.object({ * Status */ status: z.enum(['active', 'inactive']).default('active'), + + /** + * Custom metadata key-value pairs for extensibility + */ + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }); export type EdgeLocation = z.infer; diff --git a/packages/spec/src/hub/plugin-security.zod.ts b/packages/spec/src/hub/plugin-security.zod.ts index e8c4e45be..41db97896 100644 --- a/packages/spec/src/hub/plugin-security.zod.ts +++ b/packages/spec/src/hub/plugin-security.zod.ts @@ -28,7 +28,7 @@ export const VulnerabilitySeverity = z.enum([ 'medium', 'low', 'info', -]); +]).describe('Severity level of a security vulnerability'); export type VulnerabilitySeverity = z.infer; @@ -49,31 +49,31 @@ export const SecurityVulnerabilitySchema = z.object({ /** * Title */ - title: z.string(), + title: z.string().describe('Short title summarizing the vulnerability'), /** * Description */ - description: z.string(), + description: z.string().describe('Detailed description of the vulnerability'), /** * Severity */ - severity: VulnerabilitySeverity, + severity: VulnerabilitySeverity.describe('Severity level of this vulnerability'), /** * CVSS score (0-10) */ - cvss: z.number().min(0).max(10).optional(), + cvss: z.number().min(0).max(10).optional().describe('CVSS score ranging from 0 to 10'), /** * Affected package */ package: z.object({ - name: z.string(), - version: z.string(), - ecosystem: z.string().optional(), - }), + name: z.string().describe('Name of the affected package'), + version: z.string().describe('Version of the affected package'), + ecosystem: z.string().optional().describe('Package ecosystem (e.g., npm, pip, maven)'), + }).describe('Affected package information'), /** * Vulnerable version range @@ -89,25 +89,25 @@ export const SecurityVulnerabilitySchema = z.object({ * References */ references: z.array(z.object({ - type: z.enum(['advisory', 'article', 'report', 'web']), - url: z.string().url(), - })).default([]), + type: z.enum(['advisory', 'article', 'report', 'web']).describe('Type of reference source'), + url: z.string().url().describe('URL of the reference'), + })).default([]).describe('External references related to the vulnerability'), /** * CWE (Common Weakness Enumeration) */ - cwe: z.array(z.string()).default([]), + cwe: z.array(z.string()).default([]).describe('CWE identifiers associated with this vulnerability'), /** * Published date */ - publishedAt: z.string().datetime().optional(), + publishedAt: z.string().datetime().optional().describe('ISO 8601 date when the vulnerability was published'), /** * Mitigation advice */ - mitigation: z.string().optional(), -}); + mitigation: z.string().optional().describe('Recommended steps to mitigate the vulnerability'), +}).describe('A known security vulnerability in a package dependency'); export type SecurityVulnerability = z.infer; @@ -118,80 +118,80 @@ export const SecurityScanResultSchema = z.object({ /** * Scan identifier */ - scanId: z.string().uuid(), + scanId: z.string().uuid().describe('Unique identifier for this security scan'), /** * Plugin being scanned */ plugin: z.object({ - id: z.string(), - version: z.string(), - }), + id: z.string().describe('Plugin identifier'), + version: z.string().describe('Plugin version that was scanned'), + }).describe('Plugin that was scanned'), /** * Scan timestamp */ - scannedAt: z.string().datetime(), + scannedAt: z.string().datetime().describe('ISO 8601 timestamp when the scan was performed'), /** * Scanner information */ scanner: z.object({ name: z.string().describe('Scanner name (e.g., snyk, osv, trivy)'), - version: z.string(), - }), + version: z.string().describe('Version of the scanner tool'), + }).describe('Information about the scanner tool used'), /** * Scan status */ - status: z.enum(['passed', 'failed', 'warning']), + status: z.enum(['passed', 'failed', 'warning']).describe('Overall result status of the security scan'), /** * Vulnerabilities found */ - vulnerabilities: z.array(SecurityVulnerabilitySchema), + vulnerabilities: z.array(SecurityVulnerabilitySchema).describe('List of vulnerabilities discovered during the scan'), /** * Vulnerability summary */ summary: z.object({ - critical: z.number().int().min(0).default(0), - high: z.number().int().min(0).default(0), - medium: z.number().int().min(0).default(0), - low: z.number().int().min(0).default(0), - info: z.number().int().min(0).default(0), - total: z.number().int().min(0).default(0), - }), + critical: z.number().int().min(0).default(0).describe('Count of critical severity vulnerabilities'), + high: z.number().int().min(0).default(0).describe('Count of high severity vulnerabilities'), + medium: z.number().int().min(0).default(0).describe('Count of medium severity vulnerabilities'), + low: z.number().int().min(0).default(0).describe('Count of low severity vulnerabilities'), + info: z.number().int().min(0).default(0).describe('Count of informational severity vulnerabilities'), + total: z.number().int().min(0).default(0).describe('Total count of all vulnerabilities'), + }).describe('Summary counts of vulnerabilities by severity'), /** * License compliance issues */ licenseIssues: z.array(z.object({ - package: z.string(), - license: z.string(), - reason: z.string(), - severity: z.enum(['error', 'warning', 'info']), - })).default([]), + package: z.string().describe('Name of the package with a license issue'), + license: z.string().describe('License identifier of the package'), + reason: z.string().describe('Reason the license is flagged'), + severity: z.enum(['error', 'warning', 'info']).describe('Severity of the license compliance issue'), + })).default([]).describe('License compliance issues found during the scan'), /** * Code quality issues */ codeQuality: z.object({ - score: z.number().min(0).max(100).optional(), + score: z.number().min(0).max(100).optional().describe('Overall code quality score from 0 to 100'), issues: z.array(z.object({ - type: z.enum(['security', 'quality', 'style']), - severity: z.enum(['error', 'warning', 'info']), - message: z.string(), - file: z.string().optional(), - line: z.number().int().optional(), - })).default([]), - }).optional(), + type: z.enum(['security', 'quality', 'style']).describe('Category of the code quality issue'), + severity: z.enum(['error', 'warning', 'info']).describe('Severity of the code quality issue'), + message: z.string().describe('Description of the code quality issue'), + file: z.string().optional().describe('File path where the issue was found'), + line: z.number().int().optional().describe('Line number where the issue was found'), + })).default([]).describe('List of individual code quality issues'), + }).optional().describe('Code quality analysis results'), /** * Next scan scheduled */ - nextScanAt: z.string().datetime().optional(), -}); + nextScanAt: z.string().datetime().optional().describe('ISO 8601 timestamp for the next scheduled scan'), +}).describe('Result of a security scan performed on a plugin'); export type SecurityScanResult = z.infer; @@ -202,20 +202,20 @@ export const SecurityPolicySchema = z.object({ /** * Policy identifier */ - id: z.string(), + id: z.string().describe('Unique identifier for the security policy'), /** * Policy name */ - name: z.string(), + name: z.string().describe('Human-readable name of the security policy'), /** * Automatic scanning */ autoScan: z.object({ - enabled: z.boolean().default(true), - frequency: z.enum(['on-publish', 'daily', 'weekly', 'monthly']).default('daily'), - }), + enabled: z.boolean().default(true).describe('Whether automatic scanning is enabled'), + frequency: z.enum(['on-publish', 'daily', 'weekly', 'monthly']).default('daily').describe('How often automatic scans are performed'), + }).describe('Automatic security scanning configuration'), /** * Vulnerability thresholds @@ -224,18 +224,18 @@ export const SecurityPolicySchema = z.object({ /** * Block plugin if critical vulnerabilities exceed this */ - maxCritical: z.number().int().min(0).default(0), + maxCritical: z.number().int().min(0).default(0).describe('Maximum allowed critical vulnerabilities before blocking'), /** * Block plugin if high vulnerabilities exceed this */ - maxHigh: z.number().int().min(0).default(0), + maxHigh: z.number().int().min(0).default(0).describe('Maximum allowed high vulnerabilities before blocking'), /** * Warn if medium vulnerabilities exceed this */ - maxMedium: z.number().int().min(0).default(5), - }), + maxMedium: z.number().int().min(0).default(5).describe('Maximum allowed medium vulnerabilities before warning'), + }).describe('Vulnerability count thresholds for policy enforcement'), /** * Allowed licenses @@ -246,7 +246,7 @@ export const SecurityPolicySchema = z.object({ 'BSD-3-Clause', 'BSD-2-Clause', 'ISC', - ]), + ]).describe('List of SPDX license identifiers that are permitted'), /** * Prohibited licenses @@ -254,15 +254,15 @@ export const SecurityPolicySchema = z.object({ prohibitedLicenses: z.array(z.string()).default([ 'GPL-3.0', 'AGPL-3.0', - ]), + ]).describe('List of SPDX license identifiers that are prohibited'), /** * Code signing requirements */ codeSigning: z.object({ - required: z.boolean().default(false), - allowedSigners: z.array(z.string()).default([]), - }).optional(), + required: z.boolean().default(false).describe('Whether code signing is required for plugins'), + allowedSigners: z.array(z.string()).default([]).describe('List of trusted signer identities'), + }).optional().describe('Code signing requirements for plugin artifacts'), /** * Sandbox restrictions @@ -271,29 +271,29 @@ export const SecurityPolicySchema = z.object({ /** * Restrict network access */ - networkAccess: z.enum(['none', 'localhost', 'allowlist', 'all']).default('all'), + networkAccess: z.enum(['none', 'localhost', 'allowlist', 'all']).default('all').describe('Level of network access granted to the plugin'), /** * Allowed network destinations (if allowlist) */ - allowedDestinations: z.array(z.string()).default([]), + allowedDestinations: z.array(z.string()).default([]).describe('Permitted network destinations when using allowlist mode'), /** * File system access */ - filesystemAccess: z.enum(['none', 'read-only', 'temp-only', 'full']).default('full'), + filesystemAccess: z.enum(['none', 'read-only', 'temp-only', 'full']).default('full').describe('Level of file system access granted to the plugin'), /** * Maximum memory (MB) */ - maxMemoryMB: z.number().int().positive().optional(), + maxMemoryMB: z.number().int().positive().optional().describe('Maximum memory allocation in megabytes'), /** * Maximum CPU time (seconds) */ - maxCPUSeconds: z.number().int().positive().optional(), - }).optional(), -}); + maxCPUSeconds: z.number().int().positive().optional().describe('Maximum CPU time allowed in seconds'), + }).optional().describe('Sandbox restrictions for plugin execution'), +}).describe('Security policy governing plugin scanning and enforcement'); export type SecurityPolicy = z.infer; @@ -308,7 +308,7 @@ export const PackageDependencySchema = z.object({ /** * Package name/ID */ - name: z.string(), + name: z.string().describe('Package name or identifier'), /** * Version constraint (semver range) @@ -318,13 +318,13 @@ export const PackageDependencySchema = z.object({ /** * Dependency type */ - type: z.enum(['required', 'optional', 'peer', 'dev']).default('required'), + type: z.enum(['required', 'optional', 'peer', 'dev']).default('required').describe('Category of the dependency relationship'), /** * Resolved version (filled during resolution) */ - resolvedVersion: z.string().optional(), -}); + resolvedVersion: z.string().optional().describe('Concrete version resolved during dependency resolution'), +}).describe('A package dependency with its version constraint'); export type PackageDependency = z.infer; @@ -335,38 +335,38 @@ export const DependencyGraphNodeSchema = z.object({ /** * Package identifier */ - id: z.string(), + id: z.string().describe('Unique identifier of the package'), /** * Package version */ - version: z.string(), + version: z.string().describe('Resolved version of the package'), /** * Dependencies of this package */ - dependencies: z.array(PackageDependencySchema).default([]), + dependencies: z.array(PackageDependencySchema).default([]).describe('Dependencies required by this package'), /** * Depth in dependency tree */ - depth: z.number().int().min(0), + depth: z.number().int().min(0).describe('Depth level in the dependency tree (0 = root)'), /** * Whether this is a direct dependency */ - isDirect: z.boolean(), + isDirect: z.boolean().describe('Whether this is a direct (top-level) dependency'), /** * Package metadata */ metadata: z.object({ - name: z.string(), - description: z.string().optional(), - license: z.string().optional(), - homepage: z.string().url().optional(), - }).optional(), -}); + name: z.string().describe('Display name of the package'), + description: z.string().optional().describe('Short description of the package'), + license: z.string().optional().describe('SPDX license identifier of the package'), + homepage: z.string().url().optional().describe('Homepage URL of the package'), + }).optional().describe('Additional metadata about the package'), +}).describe('A node in the dependency graph representing a resolved package'); export type DependencyGraphNode = z.infer; @@ -378,14 +378,14 @@ export const DependencyGraphSchema = z.object({ * Root package */ root: z.object({ - id: z.string(), - version: z.string(), - }), + id: z.string().describe('Identifier of the root package'), + version: z.string().describe('Version of the root package'), + }).describe('Root package of the dependency graph'), /** * All nodes in the graph */ - nodes: z.array(DependencyGraphNodeSchema), + nodes: z.array(DependencyGraphNodeSchema).describe('All resolved package nodes in the dependency graph'), /** * Edges (dependency relationships) @@ -394,17 +394,17 @@ export const DependencyGraphSchema = z.object({ from: z.string().describe('Package ID'), to: z.string().describe('Package ID'), constraint: z.string().describe('Version constraint'), - })), + })).describe('Directed edges representing dependency relationships'), /** * Resolution statistics */ stats: z.object({ - totalDependencies: z.number().int().min(0), - directDependencies: z.number().int().min(0), - maxDepth: z.number().int().min(0), - }), -}); + totalDependencies: z.number().int().min(0).describe('Total number of resolved dependencies'), + directDependencies: z.number().int().min(0).describe('Number of direct (top-level) dependencies'), + maxDepth: z.number().int().min(0).describe('Maximum depth of the dependency tree'), + }).describe('Summary statistics for the dependency graph'), +}).describe('Complete dependency graph for a package and its transitive dependencies'); export type DependencyGraph = z.infer; @@ -415,31 +415,31 @@ export const DependencyConflictSchema = z.object({ /** * Package with conflict */ - package: z.string(), + package: z.string().describe('Name of the package with conflicting version requirements'), /** * Conflicting versions */ conflicts: z.array(z.object({ - version: z.string(), + version: z.string().describe('Conflicting version of the package'), requestedBy: z.array(z.string()).describe('Packages that require this version'), - constraint: z.string(), - })), + constraint: z.string().describe('Semver constraint that produced this version requirement'), + })).describe('List of conflicting version requirements'), /** * Suggested resolution */ resolution: z.object({ - strategy: z.enum(['pick-highest', 'pick-lowest', 'manual']), - version: z.string().optional(), - reason: z.string().optional(), - }).optional(), + strategy: z.enum(['pick-highest', 'pick-lowest', 'manual']).describe('Strategy used to resolve the conflict'), + version: z.string().optional().describe('Resolved version selected by the strategy'), + reason: z.string().optional().describe('Explanation of why this resolution was chosen'), + }).optional().describe('Suggested resolution for the conflict'), /** * Severity */ - severity: z.enum(['error', 'warning', 'info']), -}); + severity: z.enum(['error', 'warning', 'info']).describe('Severity level of the dependency conflict'), +}).describe('A detected conflict between dependency version requirements'); export type DependencyConflict = z.infer; @@ -450,36 +450,36 @@ export const DependencyResolutionResultSchema = z.object({ /** * Resolution status */ - status: z.enum(['success', 'conflict', 'error']), + status: z.enum(['success', 'conflict', 'error']).describe('Overall status of the dependency resolution'), /** * Resolved dependency graph */ - graph: DependencyGraphSchema.optional(), + graph: DependencyGraphSchema.optional().describe('Resolved dependency graph if resolution succeeded'), /** * Conflicts detected */ - conflicts: z.array(DependencyConflictSchema).default([]), + conflicts: z.array(DependencyConflictSchema).default([]).describe('List of dependency conflicts detected during resolution'), /** * Errors encountered */ errors: z.array(z.object({ - package: z.string(), - error: z.string(), - })).default([]), + package: z.string().describe('Name of the package that caused the error'), + error: z.string().describe('Error message describing what went wrong'), + })).default([]).describe('Errors encountered during dependency resolution'), /** * Installation order (topological sort) */ - installOrder: z.array(z.string()).default([]), + installOrder: z.array(z.string()).default([]).describe('Topologically sorted list of package IDs for installation'), /** * Resolution time (ms) */ - resolvedIn: z.number().int().min(0).optional(), -}); + resolvedIn: z.number().int().min(0).optional().describe('Time taken to resolve dependencies in milliseconds'), +}).describe('Result of a dependency resolution process'); export type DependencyResolutionResult = z.infer; @@ -494,12 +494,12 @@ export const SBOMEntrySchema = z.object({ /** * Component name */ - name: z.string(), + name: z.string().describe('Name of the software component'), /** * Component version */ - version: z.string(), + version: z.string().describe('Version of the software component'), /** * Package URL (purl) @@ -509,32 +509,32 @@ export const SBOMEntrySchema = z.object({ /** * License */ - license: z.string().optional(), + license: z.string().optional().describe('SPDX license identifier of the component'), /** * Hashes */ hashes: z.object({ - sha256: z.string().optional(), - sha512: z.string().optional(), - }).optional(), + sha256: z.string().optional().describe('SHA-256 hash of the component artifact'), + sha512: z.string().optional().describe('SHA-512 hash of the component artifact'), + }).optional().describe('Cryptographic hashes for integrity verification'), /** * Supplier */ supplier: z.object({ - name: z.string(), - url: z.string().url().optional(), - }).optional(), + name: z.string().describe('Name of the component supplier'), + url: z.string().url().optional().describe('URL of the component supplier'), + }).optional().describe('Supplier information for the component'), /** * External references */ externalRefs: z.array(z.object({ - type: z.enum(['website', 'repository', 'documentation', 'issue-tracker']), - url: z.string().url(), - })).default([]), -}); + type: z.enum(['website', 'repository', 'documentation', 'issue-tracker']).describe('Type of external reference'), + url: z.string().url().describe('URL of the external reference'), + })).default([]).describe('External references related to the component'), +}).describe('A single entry in a Software Bill of Materials'); export type SBOMEntry = z.infer; @@ -545,40 +545,40 @@ export const SBOMSchema = z.object({ /** * SBOM format */ - format: z.enum(['spdx', 'cyclonedx']).default('cyclonedx'), + format: z.enum(['spdx', 'cyclonedx']).default('cyclonedx').describe('SBOM standard format used'), /** * SBOM version */ - version: z.string(), + version: z.string().describe('Version of the SBOM specification'), /** * Plugin metadata */ plugin: z.object({ - id: z.string(), - version: z.string(), - name: z.string(), - }), + id: z.string().describe('Plugin identifier'), + version: z.string().describe('Plugin version'), + name: z.string().describe('Human-readable plugin name'), + }).describe('Metadata about the plugin this SBOM describes'), /** * Components (dependencies) */ - components: z.array(SBOMEntrySchema), + components: z.array(SBOMEntrySchema).describe('List of software components included in the plugin'), /** * Generation timestamp */ - generatedAt: z.string().datetime(), + generatedAt: z.string().datetime().describe('ISO 8601 timestamp when the SBOM was generated'), /** * Generator tool */ generator: z.object({ - name: z.string(), - version: z.string(), - }).optional(), -}); + name: z.string().describe('Name of the SBOM generator tool'), + version: z.string().describe('Version of the SBOM generator tool'), + }).optional().describe('Tool used to generate this SBOM'), +}).describe('Software Bill of Materials for a plugin'); export type SBOM = z.infer; @@ -590,12 +590,12 @@ export const PluginProvenanceSchema = z.object({ /** * Plugin identifier */ - pluginId: z.string(), + pluginId: z.string().describe('Unique identifier of the plugin'), /** * Plugin version */ - version: z.string(), + version: z.string().describe('Version of the plugin artifact'), /** * Build information @@ -604,66 +604,66 @@ export const PluginProvenanceSchema = z.object({ /** * Build timestamp */ - timestamp: z.string().datetime(), + timestamp: z.string().datetime().describe('ISO 8601 timestamp when the build was produced'), /** * Build environment */ environment: z.object({ - os: z.string(), - arch: z.string(), - nodeVersion: z.string(), - }).optional(), + os: z.string().describe('Operating system used for the build'), + arch: z.string().describe('CPU architecture used for the build'), + nodeVersion: z.string().describe('Node.js version used for the build'), + }).optional().describe('Environment details where the build was executed'), /** * Source repository */ source: z.object({ - repository: z.string().url(), - commit: z.string().regex(/^[a-f0-9]{40}$/), - branch: z.string().optional(), - tag: z.string().optional(), - }).optional(), + repository: z.string().url().describe('URL of the source repository'), + commit: z.string().regex(/^[a-f0-9]{40}$/).describe('Full SHA-1 commit hash of the source'), + branch: z.string().optional().describe('Branch name the build was produced from'), + tag: z.string().optional().describe('Git tag associated with the build'), + }).optional().describe('Source repository information for the build'), /** * Builder identity */ builder: z.object({ - name: z.string(), - email: z.string().email().optional(), - }).optional(), - }), + name: z.string().describe('Name of the person or system that produced the build'), + email: z.string().email().optional().describe('Email address of the builder'), + }).optional().describe('Identity of the builder who produced the artifact'), + }).describe('Build provenance information'), /** * Artifact hashes */ artifacts: z.array(z.object({ - filename: z.string(), - sha256: z.string(), - size: z.number().int().positive(), - })), + filename: z.string().describe('Name of the artifact file'), + sha256: z.string().describe('SHA-256 hash of the artifact'), + size: z.number().int().positive().describe('Size of the artifact in bytes'), + })).describe('List of build artifacts with integrity hashes'), /** * Signatures */ signatures: z.array(z.object({ - algorithm: z.enum(['rsa', 'ecdsa', 'ed25519']), - publicKey: z.string(), - signature: z.string(), - signedBy: z.string(), - timestamp: z.string().datetime(), - })).default([]), + algorithm: z.enum(['rsa', 'ecdsa', 'ed25519']).describe('Cryptographic algorithm used for signing'), + publicKey: z.string().describe('Public key used to verify the signature'), + signature: z.string().describe('Digital signature value'), + signedBy: z.string().describe('Identity of the signer'), + timestamp: z.string().datetime().describe('ISO 8601 timestamp when the signature was created'), + })).default([]).describe('Cryptographic signatures for the plugin artifact'), /** * Attestations */ attestations: z.array(z.object({ - type: z.enum(['code-review', 'security-scan', 'test-results', 'ci-build']), - status: z.enum(['passed', 'failed']), - url: z.string().url().optional(), - timestamp: z.string().datetime(), - })).default([]), -}); + type: z.enum(['code-review', 'security-scan', 'test-results', 'ci-build']).describe('Type of attestation'), + status: z.enum(['passed', 'failed']).describe('Result status of the attestation'), + url: z.string().url().optional().describe('URL with details about the attestation'), + timestamp: z.string().datetime().describe('ISO 8601 timestamp when the attestation was issued'), + })).default([]).describe('Verification attestations for the plugin'), +}).describe('Verifiable provenance and chain of custody for a plugin artifact'); export type PluginProvenance = z.infer; @@ -678,12 +678,12 @@ export const PluginTrustScoreSchema = z.object({ /** * Plugin identifier */ - pluginId: z.string(), + pluginId: z.string().describe('Unique identifier of the plugin'), /** * Overall trust score (0-100) */ - score: z.number().min(0).max(100), + score: z.number().min(0).max(100).describe('Overall trust score from 0 to 100'), /** * Score components @@ -692,33 +692,33 @@ export const PluginTrustScoreSchema = z.object({ /** * Vendor reputation (0-100) */ - vendorReputation: z.number().min(0).max(100), + vendorReputation: z.number().min(0).max(100).describe('Vendor reputation score from 0 to 100'), /** * Security scan results (0-100) */ - securityScore: z.number().min(0).max(100), + securityScore: z.number().min(0).max(100).describe('Security scan results score from 0 to 100'), /** * Code quality (0-100) */ - codeQuality: z.number().min(0).max(100), + codeQuality: z.number().min(0).max(100).describe('Code quality score from 0 to 100'), /** * Community engagement (0-100) */ - communityScore: z.number().min(0).max(100), + communityScore: z.number().min(0).max(100).describe('Community engagement score from 0 to 100'), /** * Update frequency (0-100) */ - maintenanceScore: z.number().min(0).max(100), - }), + maintenanceScore: z.number().min(0).max(100).describe('Maintenance and update frequency score from 0 to 100'), + }).describe('Individual score components contributing to the overall trust score'), /** * Trust level */ - level: z.enum(['verified', 'trusted', 'neutral', 'untrusted', 'blocked']), + level: z.enum(['verified', 'trusted', 'neutral', 'untrusted', 'blocked']).describe('Computed trust level based on the overall score'), /** * Verification badges @@ -730,13 +730,13 @@ export const PluginTrustScoreSchema = z.object({ 'code-signed', // Digitally signed 'open-source', // Open source 'popular', // High downloads - ])).default([]), + ])).default([]).describe('Verification badges earned by the plugin'), /** * Last updated */ - updatedAt: z.string().datetime(), -}); + updatedAt: z.string().datetime().describe('ISO 8601 timestamp when the trust score was last updated'), +}).describe('Trust score and verification status for a plugin'); export type PluginTrustScore = z.infer; diff --git a/packages/spec/src/kernel/plugin-structure.zod.ts b/packages/spec/src/kernel/plugin-structure.zod.ts index b5d9db028..4a00f2734 100644 --- a/packages/spec/src/kernel/plugin-structure.zod.ts +++ b/packages/spec/src/kernel/plugin-structure.zod.ts @@ -79,6 +79,7 @@ export const OpsFilePathSchema = z.string().describe('Validates a file path agai export const OpsDomainModuleSchema = z.object({ name: z.string().regex(SNAKE_CASE_REGEX).describe('Module name (snake_case)'), files: z.array(z.string()).describe('List of files in this module'), + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }).describe('Scanned domain module representing a plugin folder').superRefine((module, ctx) => { // Rule: Must have an index.ts if (!module.files.includes('index.ts')) { @@ -95,6 +96,7 @@ export const OpsDomainModuleSchema = z.object({ export const OpsPluginStructureSchema = z.object({ root: z.string().describe('Root directory path of the plugin project'), files: z.array(z.string()).describe('List of all file paths relative to root'), + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }).describe('Full plugin project layout validated against OPS conventions').superRefine((project, ctx) => { // Check for configuration file if (!project.files.includes('objectstack.config.ts')) { diff --git a/packages/spec/src/system/change-management.zod.ts b/packages/spec/src/system/change-management.zod.ts index 08e641aaa..7112524cc 100644 --- a/packages/spec/src/system/change-management.zod.ts +++ b/packages/spec/src/system/change-management.zod.ts @@ -361,6 +361,11 @@ export const ChangeRequestSchema = z.object({ */ url: z.string().url().describe('Attachment URL'), })).optional().describe('Attachments'), + + /** + * Custom metadata key-value pairs for extensibility + */ + metadata: z.record(z.string(), z.unknown()).optional().describe('Custom metadata key-value pairs for extensibility'), }); // Type exports