@objectstack/spec 2.0.5 → 2.0.7

package/json-schema/api/OpenApi31Extensions.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "webhooks": {
+      "description": "OpenAPI 3.1 webhooks (top-level webhook definitions)",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z_][a-z0-9_]*$",
+            "description": "Webhook event identifier (snake_case)"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable event description"
+          },
+          "method": {
+            "default": "POST",
+            "description": "HTTP method for webhook delivery",
+            "type": "string",
+            "enum": [
+              "GET",
+              "POST",
+              "PUT",
+              "DELETE",
+              "PATCH",
+              "HEAD",
+              "OPTIONS"
+            ]
+          },
+          "payloadSchema": {
+            "type": "string",
+            "description": "JSON Schema $ref for the webhook payload"
+          },
+          "headers": {
+            "description": "Custom headers to include in webhook delivery",
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "security": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "hmac_sha256",
+                "basic",
+                "bearer",
+                "api_key"
+              ]
+            },
+            "description": "Supported authentication methods for webhook verification"
+          }
+        },
+        "required": [
+          "name",
+          "description",
+          "method",
+          "payloadSchema",
+          "security"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "callbacks": {
+      "description": "OpenAPI 3.1 callbacks (async response definitions)",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "pattern": "^[a-z_][a-z0-9_]*$",
+              "description": "Callback identifier (snake_case)"
+            },
+            "expression": {
+              "type": "string",
+              "description": "Runtime expression (e.g., {$request.body#/callbackUrl})"
+            },
+            "method": {
+              "type": "string",
+              "enum": [
+                "GET",
+                "POST",
+                "PUT",
+                "DELETE",
+                "PATCH",
+                "HEAD",
+                "OPTIONS"
+              ],
+              "description": "HTTP method for callback request"
+            },
+            "url": {
+              "type": "string",
+              "description": "Callback URL template with runtime expressions"
+            }
+          },
+          "required": [
+            "name",
+            "expression",
+            "method",
+            "url"
+          ],
+          "additionalProperties": false
+        }
+      }
+    },
+    "jsonSchemaDialect": {
+      "default": "https://json-schema.org/draft/2020-12/schema",
+      "description": "JSON Schema dialect for schema definitions",
+      "type": "string"
+    },
+    "pathItemReferences": {
+      "default": false,
+      "description": "Allow $ref in path items (OpenAPI 3.1 feature)",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "jsonSchemaDialect",
+    "pathItemReferences"
+  ],
+  "additionalProperties": false
+}

package/json-schema/api/OperatorMapping.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "operator": {
+      "type": "string",
+      "description": "Unified DSL operator"
+    },
+    "rest": {
+      "description": "REST query parameter template",
+      "type": "string"
+    },
+    "graphql": {
+      "description": "GraphQL where clause template",
+      "type": "string"
+    },
+    "odata": {
+      "description": "OData $filter expression template",
+      "type": "string"
+    }
+  },
+  "required": [
+    "operator"
+  ],
+  "additionalProperties": false
+}

package/json-schema/api/PresenceStatus.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "string",
+  "enum": [
+    "online",
+    "away",
+    "busy",
+    "offline"
+  ]
+}

package/json-schema/api/QueryAdapterConfig.json

@@ -0,0 +1,272 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "operatorMappings": {
+      "description": "Custom operator mappings",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "operator": {
+            "type": "string",
+            "description": "Unified DSL operator"
+          },
+          "rest": {
+            "description": "REST query parameter template",
+            "type": "string"
+          },
+          "graphql": {
+            "description": "GraphQL where clause template",
+            "type": "string"
+          },
+          "odata": {
+            "description": "OData $filter expression template",
+            "type": "string"
+          }
+        },
+        "required": [
+          "operator"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "rest": {
+      "description": "REST query adapter configuration",
+      "type": "object",
+      "properties": {
+        "filterStyle": {
+          "default": "bracket",
+          "description": "REST filter parameter encoding style",
+          "type": "string",
+          "enum": [
+            "bracket",
+            "dot",
+            "flat",
+            "rsql"
+          ]
+        },
+        "pagination": {
+          "description": "Pagination parameter name mappings",
+          "type": "object",
+          "properties": {
+            "limitParam": {
+              "default": "limit",
+              "description": "Page size parameter name",
+              "type": "string"
+            },
+            "offsetParam": {
+              "default": "offset",
+              "description": "Offset parameter name",
+              "type": "string"
+            },
+            "cursorParam": {
+              "default": "cursor",
+              "description": "Cursor parameter name",
+              "type": "string"
+            },
+            "pageParam": {
+              "default": "page",
+              "description": "Page number parameter name",
+              "type": "string"
+            }
+          },
+          "required": [
+            "limitParam",
+            "offsetParam",
+            "cursorParam",
+            "pageParam"
+          ],
+          "additionalProperties": false
+        },
+        "sorting": {
+          "description": "Sort parameter mapping",
+          "type": "object",
+          "properties": {
+            "param": {
+              "default": "sort",
+              "description": "Sort parameter name",
+              "type": "string"
+            },
+            "format": {
+              "default": "comma",
+              "description": "Sort parameter encoding format",
+              "type": "string",
+              "enum": [
+                "comma",
+                "array",
+                "pipe"
+              ]
+            }
+          },
+          "required": [
+            "param",
+            "format"
+          ],
+          "additionalProperties": false
+        },
+        "fieldsParam": {
+          "default": "fields",
+          "description": "Field selection parameter name",
+          "type": "string"
+        }
+      },
+      "required": [
+        "filterStyle",
+        "fieldsParam"
+      ],
+      "additionalProperties": false
+    },
+    "graphql": {
+      "description": "GraphQL query adapter configuration",
+      "type": "object",
+      "properties": {
+        "filterArgName": {
+          "default": "where",
+          "description": "GraphQL filter argument name",
+          "type": "string"
+        },
+        "filterStyle": {
+          "default": "nested",
+          "description": "GraphQL filter nesting style",
+          "type": "string",
+          "enum": [
+            "nested",
+            "flat",
+            "array"
+          ]
+        },
+        "pagination": {
+          "description": "Pagination argument name mappings",
+          "type": "object",
+          "properties": {
+            "limitArg": {
+              "default": "limit",
+              "description": "Page size argument name",
+              "type": "string"
+            },
+            "offsetArg": {
+              "default": "offset",
+              "description": "Offset argument name",
+              "type": "string"
+            },
+            "firstArg": {
+              "default": "first",
+              "description": "Relay \"first\" argument name",
+              "type": "string"
+            },
+            "afterArg": {
+              "default": "after",
+              "description": "Relay \"after\" cursor argument name",
+              "type": "string"
+            }
+          },
+          "required": [
+            "limitArg",
+            "offsetArg",
+            "firstArg",
+            "afterArg"
+          ],
+          "additionalProperties": false
+        },
+        "sorting": {
+          "description": "Sort argument mapping",
+          "type": "object",
+          "properties": {
+            "argName": {
+              "default": "orderBy",
+              "description": "Sort argument name",
+              "type": "string"
+            },
+            "format": {
+              "default": "enum",
+              "description": "Sort argument format",
+              "type": "string",
+              "enum": [
+                "enum",
+                "array"
+              ]
+            }
+          },
+          "required": [
+            "argName",
+            "format"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "filterArgName",
+        "filterStyle"
+      ],
+      "additionalProperties": false
+    },
+    "odata": {
+      "description": "OData query adapter configuration",
+      "type": "object",
+      "properties": {
+        "version": {
+          "default": "v4",
+          "description": "OData version",
+          "type": "string",
+          "enum": [
+            "v2",
+            "v4"
+          ]
+        },
+        "usePrefix": {
+          "default": true,
+          "description": "Use $ prefix for system query options ($filter vs filter)",
+          "type": "boolean"
+        },
+        "stringFunctions": {
+          "description": "Supported OData string functions",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "contains",
+              "startswith",
+              "endswith",
+              "tolower",
+              "toupper",
+              "trim",
+              "concat",
+              "substring",
+              "length"
+            ]
+          }
+        },
+        "expand": {
+          "description": "$expand configuration",
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": true,
+              "description": "Enable $expand support",
+              "type": "boolean"
+            },
+            "maxDepth": {
+              "default": 3,
+              "description": "Maximum expand depth",
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            }
+          },
+          "required": [
+            "enabled",
+            "maxDepth"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "version",
+        "usePrefix"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/json-schema/api/QueryAdapterTarget.json

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

package/json-schema/api/QueryOptimizationConfig.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "preventNPlusOne": {
+      "type": "boolean",
+      "description": "Enable N+1 query detection and prevention"
+    },
+    "dataLoader": {
+      "description": "DataLoader batch loading configuration",
+      "type": "object",
+      "properties": {
+        "maxBatchSize": {
+          "default": 100,
+          "description": "Maximum number of keys per batch load",
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "batchScheduleFn": {
+          "default": "microtask",
+          "description": "Scheduling strategy for collecting batch keys",
+          "type": "string",
+          "enum": [
+            "microtask",
+            "timeout",
+            "manual"
+          ]
+        },
+        "cacheEnabled": {
+          "default": true,
+          "description": "Enable per-request result caching",
+          "type": "boolean"
+        },
+        "cacheKeyFn": {
+          "description": "Name or identifier of the cache key function",
+          "type": "string"
+        },
+        "cacheTtl": {
+          "description": "Cache time-to-live in seconds (0 = no expiration)",
+          "type": "number",
+          "minimum": 0
+        },
+        "coalesceRequests": {
+          "default": true,
+          "description": "Deduplicate identical requests within a batch window",
+          "type": "boolean"
+        },
+        "maxConcurrency": {
+          "description": "Maximum parallel batch requests",
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "maxBatchSize",
+        "batchScheduleFn",
+        "cacheEnabled",
+        "coalesceRequests"
+      ],
+      "additionalProperties": false
+    },
+    "batchStrategy": {
+      "description": "Batch loading strategy configuration",
+      "type": "object",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": [
+            "dataloader",
+            "windowed",
+            "prefetch"
+          ],
+          "description": "Batch loading strategy type"
+        },
+        "windowMs": {
+          "description": "Collection window duration in milliseconds (for windowed strategy)",
+          "type": "number"
+        },
+        "prefetchDepth": {
+          "description": "Depth of relation prefetching (for prefetch strategy)",
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "associationLoading": {
+          "default": "batch",
+          "description": "How to load related associations",
+          "type": "string",
+          "enum": [
+            "lazy",
+            "eager",
+            "batch"
+          ]
+        }
+      },
+      "required": [
+        "strategy",
+        "associationLoading"
+      ],
+      "additionalProperties": false
+    },
+    "maxQueryDepth": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991,
+      "description": "Maximum depth for nested relation queries"
+    },
+    "queryComplexityLimit": {
+      "description": "Maximum allowed query complexity score",
+      "type": "number"
+    },
+    "enableQueryPlan": {
+      "default": false,
+      "description": "Log query execution plans for debugging",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "preventNPlusOne",
+    "maxQueryDepth",
+    "enableQueryPlan"
+  ],
+  "additionalProperties": false
+}

package/json-schema/api/RealtimeRecordAction.json

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

package/json-schema/api/RestQueryAdapter.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "filterStyle": {
+      "default": "bracket",
+      "description": "REST filter parameter encoding style",
+      "type": "string",
+      "enum": [
+        "bracket",
+        "dot",
+        "flat",
+        "rsql"
+      ]
+    },
+    "pagination": {
+      "description": "Pagination parameter name mappings",
+      "type": "object",
+      "properties": {
+        "limitParam": {
+          "default": "limit",
+          "description": "Page size parameter name",
+          "type": "string"
+        },
+        "offsetParam": {
+          "default": "offset",
+          "description": "Offset parameter name",
+          "type": "string"
+        },
+        "cursorParam": {
+          "default": "cursor",
+          "description": "Cursor parameter name",
+          "type": "string"
+        },
+        "pageParam": {
+          "default": "page",
+          "description": "Page number parameter name",
+          "type": "string"
+        }
+      },
+      "required": [
+        "limitParam",
+        "offsetParam",
+        "cursorParam",
+        "pageParam"
+      ],
+      "additionalProperties": false
+    },
+    "sorting": {
+      "description": "Sort parameter mapping",
+      "type": "object",
+      "properties": {
+        "param": {
+          "default": "sort",
+          "description": "Sort parameter name",
+          "type": "string"
+        },
+        "format": {
+          "default": "comma",
+          "description": "Sort parameter encoding format",
+          "type": "string",
+          "enum": [
+            "comma",
+            "array",
+            "pipe"
+          ]
+        }
+      },
+      "required": [
+        "param",
+        "format"
+      ],
+      "additionalProperties": false
+    },
+    "fieldsParam": {
+      "default": "fields",
+      "description": "Field selection parameter name",
+      "type": "string"
+    }
+  },
+  "required": [
+    "filterStyle",
+    "fieldsParam"
+  ],
+  "additionalProperties": false
+}