@objectstack/spec 2.0.5 → 2.0.7

package/json-schema/system/DistributedCacheConfig.json

@@ -0,0 +1,269 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "default": false,
+      "description": "Enable application-level caching",
+      "type": "boolean"
+    },
+    "tiers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Unique cache tier name"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "memory",
+              "redis",
+              "memcached",
+              "cdn"
+            ],
+            "description": "Cache backend type"
+          },
+          "maxSize": {
+            "description": "Max size in MB",
+            "type": "number"
+          },
+          "ttl": {
+            "default": 300,
+            "description": "Default TTL in seconds",
+            "type": "number"
+          },
+          "strategy": {
+            "default": "lru",
+            "description": "Eviction strategy",
+            "type": "string",
+            "enum": [
+              "lru",
+              "lfu",
+              "fifo",
+              "ttl",
+              "adaptive"
+            ]
+          },
+          "warmup": {
+            "default": false,
+            "description": "Pre-populate cache on startup",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "name",
+          "type",
+          "ttl",
+          "strategy",
+          "warmup"
+        ],
+        "additionalProperties": false,
+        "description": "Configuration for a single cache tier in the hierarchy"
+      },
+      "description": "Ordered cache tier hierarchy"
+    },
+    "invalidation": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "trigger": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "delete",
+              "manual"
+            ],
+            "description": "Event that triggers invalidation"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "key",
+              "pattern",
+              "tag",
+              "all"
+            ],
+            "description": "Invalidation scope"
+          },
+          "pattern": {
+            "description": "Key pattern for pattern-based invalidation",
+            "type": "string"
+          },
+          "tags": {
+            "description": "Cache tags to invalidate",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "trigger",
+          "scope"
+        ],
+        "additionalProperties": false,
+        "description": "Rule defining when and how cached entries are invalidated"
+      },
+      "description": "Cache invalidation rules"
+    },
+    "prefetch": {
+      "default": false,
+      "description": "Enable cache prefetching",
+      "type": "boolean"
+    },
+    "compression": {
+      "default": false,
+      "description": "Enable data compression in cache",
+      "type": "boolean"
+    },
+    "encryption": {
+      "default": false,
+      "description": "Enable encryption for cached data",
+      "type": "boolean"
+    },
+    "consistency": {
+      "description": "Distributed cache consistency strategy",
+      "type": "string",
+      "enum": [
+        "write_through",
+        "write_behind",
+        "write_around",
+        "refresh_ahead"
+      ]
+    },
+    "avalanchePrevention": {
+      "description": "Cache avalanche and stampede prevention",
+      "type": "object",
+      "properties": {
+        "jitterTtl": {
+          "description": "TTL jitter to prevent simultaneous expiration",
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": false,
+              "description": "Add random jitter to TTL values",
+              "type": "boolean"
+            },
+            "maxJitterSeconds": {
+              "default": 60,
+              "description": "Maximum jitter added to TTL in seconds",
+              "type": "number"
+            }
+          },
+          "required": [
+            "enabled",
+            "maxJitterSeconds"
+          ],
+          "additionalProperties": false
+        },
+        "circuitBreaker": {
+          "description": "Circuit breaker for backend protection",
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": false,
+              "description": "Enable circuit breaker for backend protection",
+              "type": "boolean"
+            },
+            "failureThreshold": {
+              "default": 5,
+              "description": "Failures before circuit opens",
+              "type": "number"
+            },
+            "resetTimeout": {
+              "default": 30,
+              "description": "Seconds before half-open state",
+              "type": "number"
+            }
+          },
+          "required": [
+            "enabled",
+            "failureThreshold",
+            "resetTimeout"
+          ],
+          "additionalProperties": false
+        },
+        "lockout": {
+          "description": "Lock-based stampede prevention",
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": false,
+              "description": "Enable cache locking for key regeneration",
+              "type": "boolean"
+            },
+            "lockTimeoutMs": {
+              "default": 5000,
+              "description": "Maximum lock wait time in milliseconds",
+              "type": "number"
+            }
+          },
+          "required": [
+            "enabled",
+            "lockTimeoutMs"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "warmup": {
+      "description": "Cache warmup strategy",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "description": "Enable cache warmup",
+          "type": "boolean"
+        },
+        "strategy": {
+          "default": "lazy",
+          "description": "Warmup strategy: eager (at startup), lazy (on first access), scheduled (cron)",
+          "type": "string",
+          "enum": [
+            "eager",
+            "lazy",
+            "scheduled"
+          ]
+        },
+        "schedule": {
+          "description": "Cron expression for scheduled warmup",
+          "type": "string"
+        },
+        "patterns": {
+          "description": "Key patterns to warm up (e.g., \"user:*\", \"config:*\")",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "concurrency": {
+          "default": 10,
+          "description": "Maximum concurrent warmup operations",
+          "type": "number"
+        }
+      },
+      "required": [
+        "enabled",
+        "strategy",
+        "concurrency"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "enabled",
+    "tiers",
+    "invalidation",
+    "prefetch",
+    "compression",
+    "encryption"
+  ],
+  "additionalProperties": false,
+  "description": "Distributed cache configuration with consistency and avalanche prevention"
+}

package/json-schema/system/FailoverConfig.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "mode": {
+      "default": "active_passive",
+      "description": "Failover mode",
+      "type": "string",
+      "enum": [
+        "active_passive",
+        "active_active",
+        "pilot_light",
+        "warm_standby"
+      ]
+    },
+    "autoFailover": {
+      "default": true,
+      "description": "Enable automatic failover",
+      "type": "boolean"
+    },
+    "healthCheckInterval": {
+      "default": 30,
+      "description": "Health check interval in seconds",
+      "type": "number"
+    },
+    "failureThreshold": {
+      "default": 3,
+      "description": "Consecutive failures before failover",
+      "type": "number"
+    },
+    "regions": {
+      "minItems": 2,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Region identifier (e.g., \"us-east-1\", \"eu-west-1\")"
+          },
+          "role": {
+            "type": "string",
+            "enum": [
+              "primary",
+              "secondary",
+              "witness"
+            ],
+            "description": "Region role"
+          },
+          "endpoint": {
+            "description": "Region endpoint URL",
+            "type": "string"
+          },
+          "priority": {
+            "description": "Failover priority (lower = higher priority)",
+            "type": "number"
+          }
+        },
+        "required": [
+          "name",
+          "role"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Multi-region configuration (minimum 2 regions)"
+    },
+    "dns": {
+      "description": "DNS failover settings",
+      "type": "object",
+      "properties": {
+        "ttl": {
+          "default": 60,
+          "description": "DNS TTL in seconds for failover",
+          "type": "number"
+        },
+        "provider": {
+          "description": "DNS provider for automatic failover",
+          "type": "string",
+          "enum": [
+            "route53",
+            "cloudflare",
+            "azure_dns",
+            "custom"
+          ]
+        }
+      },
+      "required": [
+        "ttl"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "mode",
+    "autoFailover",
+    "healthCheckInterval",
+    "failureThreshold",
+    "regions"
+  ],
+  "additionalProperties": false,
+  "description": "Failover configuration"
+}

package/json-schema/system/FailoverMode.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "string",
+  "enum": [
+    "active_passive",
+    "active_active",
+    "pilot_light",
+    "warm_standby"
+  ],
+  "description": "Failover mode"
+}

package/json-schema/system/MaskingVisibilityRule.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "dataClassification": {
+      "type": "string",
+      "enum": [
+        "pii",
+        "phi",
+        "pci",
+        "financial",
+        "confidential",
+        "internal",
+        "public"
+      ],
+      "description": "Data classification this rule applies to"
+    },
+    "defaultMasked": {
+      "default": true,
+      "description": "Whether data is masked by default",
+      "type": "boolean"
+    },
+    "unmaskRoles": {
+      "description": "Roles allowed to view unmasked data",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "auditUnmask": {
+      "default": true,
+      "description": "Log an audit event when data is unmasked",
+      "type": "boolean"
+    },
+    "requireApproval": {
+      "default": false,
+      "description": "Require explicit approval before unmasking",
+      "type": "boolean"
+    },
+    "approvalRoles": {
+      "description": "Roles that can approve unmasking requests",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "dataClassification",
+    "defaultMasked",
+    "auditUnmask",
+    "requireApproval"
+  ],
+  "additionalProperties": false,
+  "description": "Masking visibility and audit rule per data classification"
+}

package/json-schema/system/MetadataFallbackStrategy.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "string",
+  "enum": [
+    "filesystem",
+    "memory",
+    "none"
+  ]
+}

package/json-schema/system/MetadataLoaderContract.json

@@ -6,7 +6,15 @@
       "type": "string"
     },
     "protocol": {
-      "type": "string"
+      "type": "string",
+      "enum": [
+        "file:",
+        "http:",
+        "s3:",
+        "datasource:",
+        "memory:"
+      ],
+      "description": "Loader protocol identifier"
     },
     "description": {
       "type": "string"

package/json-schema/system/MetadataManagerConfig.json

@@ -2,23 +2,31 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "loaders": {
-      "type": "array",
-      "items": {}
-    },
-    "watch": {
-      "type": "boolean"
-    },
-    "cache": {
-      "type": "boolean"
+    "datasource": {
+      "description": "Datasource name reference for database persistence",
+      "type": "string"
     },
-    "basePath": {
+    "tableName": {
+      "default": "sys_metadata",
+      "description": "Database table name for metadata storage",
       "type": "string"
     },
+    "fallback": {
+      "default": "none",
+      "description": "Fallback strategy when datasource is unavailable",
+      "type": "string",
+      "enum": [
+        "filesystem",
+        "memory",
+        "none"
+      ]
+    },
     "rootDir": {
+      "description": "Root directory for filesystem-based metadata",
       "type": "string"
     },
     "formats": {
+      "description": "Enabled metadata formats",
       "type": "array",
       "items": {
         "type": "string",
@@ -33,7 +41,40 @@
         ]
       }
     },
-    "watchOptions": {}
+    "watch": {
+      "description": "Enable file watching for filesystem loaders",
+      "type": "boolean"
+    },
+    "cache": {
+      "description": "Enable metadata caching",
+      "type": "boolean"
+    },
+    "watchOptions": {
+      "description": "File watcher options",
+      "type": "object",
+      "properties": {
+        "ignored": {
+          "description": "Patterns to ignore",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "persistent": {
+          "default": true,
+          "description": "Keep process running",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "persistent"
+      ],
+      "additionalProperties": false
+    }
   },
+  "required": [
+    "tableName",
+    "fallback"
+  ],
   "additionalProperties": false
 }

package/json-schema/system/MetadataRecord.json

@@ -56,6 +56,36 @@
         "deprecated"
       ]
     },
+    "tenantId": {
+      "description": "Tenant identifier for multi-tenant isolation",
+      "type": "string"
+    },
+    "version": {
+      "default": 1,
+      "description": "Record version for optimistic concurrency control",
+      "type": "number"
+    },
+    "checksum": {
+      "description": "Content checksum for change detection",
+      "type": "string"
+    },
+    "source": {
+      "description": "Origin of this metadata record",
+      "type": "string",
+      "enum": [
+        "filesystem",
+        "database",
+        "api",
+        "migration"
+      ]
+    },
+    "tags": {
+      "description": "Classification tags for filtering and grouping",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "createdBy": {
       "type": "string"
     },
@@ -83,7 +113,8 @@
     "scope",
     "metadata",
     "strategy",
-    "state"
+    "state",
+    "version"
   ],
   "additionalProperties": false
 }

package/json-schema/system/MetadataSource.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "string",
+  "enum": [
+    "filesystem",
+    "database",
+    "api",
+    "migration"
+  ]
+}

package/json-schema/system/MutualTLSConfig.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "default": false,
+      "description": "Enable mutual TLS authentication",
+      "type": "boolean"
+    },
+    "clientCertRequired": {
+      "default": false,
+      "description": "Require client certificates for all connections",
+      "type": "boolean"
+    },
+    "trustedCAs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "PEM-encoded CA certificates or file paths"
+    },
+    "crlUrl": {
+      "description": "Certificate Revocation List (CRL) URL",
+      "type": "string"
+    },
+    "ocspUrl": {
+      "description": "Online Certificate Status Protocol (OCSP) URL",
+      "type": "string"
+    },
+    "certificateValidation": {
+      "type": "string",
+      "enum": [
+        "strict",
+        "relaxed",
+        "none"
+      ],
+      "description": "Certificate validation strictness level"
+    },
+    "allowedCNs": {
+      "description": "Allowed Common Names (CN) on client certificates",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "allowedOUs": {
+      "description": "Allowed Organizational Units (OU) on client certificates",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "pinning": {
+      "description": "Certificate pinning configuration",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable certificate pinning"
+        },
+        "pins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Pinned certificate hashes"
+        }
+      },
+      "required": [
+        "enabled",
+        "pins"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "enabled",
+    "clientCertRequired",
+    "trustedCAs",
+    "certificateValidation"
+  ],
+  "additionalProperties": false
+}