@objectstack/spec 0.2.0 → 0.3.0

package/json-schema/NLQResponse.json

@@ -0,0 +1,288 @@
+{
+  "$ref": "#/definitions/NLQResponse",
+  "definitions": {
+    "NLQResponse": {
+      "type": "object",
+      "properties": {
+        "parseResult": {
+          "type": "object",
+          "properties": {
+            "originalQuery": {
+              "type": "string"
+            },
+            "intent": {
+              "type": "string",
+              "enum": [
+                "select",
+                "aggregate",
+                "filter",
+                "sort",
+                "compare",
+                "trend",
+                "insight",
+                "create",
+                "update",
+                "delete"
+              ]
+            },
+            "intentConfidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            },
+            "entities": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "object",
+                      "field",
+                      "value",
+                      "operator",
+                      "function",
+                      "timeframe"
+                    ]
+                  },
+                  "text": {
+                    "type": "string",
+                    "description": "Original text from query"
+                  },
+                  "value": {
+                    "description": "Normalized value"
+                  },
+                  "confidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1,
+                    "description": "Confidence score"
+                  },
+                  "span": {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "items": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "type": "number"
+                      }
+                    ],
+                    "description": "Character span in query"
+                  }
+                },
+                "required": [
+                  "type",
+                  "text",
+                  "confidence"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "targetObject": {
+              "type": "string",
+              "description": "Primary object to query"
+            },
+            "fields": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "naturalLanguage": {
+                    "type": "string",
+                    "description": "NL field name (e.g., \"customer name\")"
+                  },
+                  "objectField": {
+                    "type": "string",
+                    "description": "Actual field name (e.g., \"account.name\")"
+                  },
+                  "object": {
+                    "type": "string",
+                    "description": "Object name"
+                  },
+                  "field": {
+                    "type": "string",
+                    "description": "Field name"
+                  },
+                  "confidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  }
+                },
+                "required": [
+                  "naturalLanguage",
+                  "objectField",
+                  "object",
+                  "field",
+                  "confidence"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "timeframe": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "absolute",
+                    "relative"
+                  ]
+                },
+                "start": {
+                  "type": "string",
+                  "description": "Start date (ISO format)"
+                },
+                "end": {
+                  "type": "string",
+                  "description": "End date (ISO format)"
+                },
+                "relative": {
+                  "type": "object",
+                  "properties": {
+                    "unit": {
+                      "type": "string",
+                      "enum": [
+                        "hour",
+                        "day",
+                        "week",
+                        "month",
+                        "quarter",
+                        "year"
+                      ]
+                    },
+                    "value": {
+                      "type": "integer"
+                    },
+                    "direction": {
+                      "type": "string",
+                      "enum": [
+                        "past",
+                        "future",
+                        "current"
+                      ],
+                      "default": "past"
+                    }
+                  },
+                  "required": [
+                    "unit",
+                    "value"
+                  ],
+                  "additionalProperties": false
+                },
+                "text": {
+                  "type": "string",
+                  "description": "Original timeframe text"
+                }
+              },
+              "required": [
+                "type",
+                "text"
+              ],
+              "additionalProperties": false
+            },
+            "ast": {
+              "description": "Generated ObjectQL AST"
+            },
+            "confidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Overall confidence"
+            },
+            "ambiguities": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string"
+                  },
+                  "description": {
+                    "type": "string"
+                  },
+                  "suggestions": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "required": [
+                  "type",
+                  "description"
+                ],
+                "additionalProperties": false
+              },
+              "description": "Detected ambiguities requiring clarification"
+            },
+            "alternatives": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "interpretation": {
+                    "type": "string"
+                  },
+                  "confidence": {
+                    "type": "number"
+                  },
+                  "ast": {}
+                },
+                "required": [
+                  "interpretation",
+                  "confidence"
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": [
+            "originalQuery",
+            "intent",
+            "intentConfidence",
+            "entities",
+            "confidence"
+          ],
+          "additionalProperties": false
+        },
+        "results": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": {}
+          },
+          "description": "Query results"
+        },
+        "totalCount": {
+          "type": "integer"
+        },
+        "executionTime": {
+          "type": "number",
+          "description": "Execution time in milliseconds"
+        },
+        "needsClarification": {
+          "type": "boolean",
+          "description": "Whether query needs clarification"
+        },
+        "suggestions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Query refinement suggestions"
+        }
+      },
+      "required": [
+        "parseResult",
+        "needsClarification"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/NLQTrainingExample.json

@@ -0,0 +1,120 @@
+{
+  "$ref": "#/definitions/NLQTrainingExample",
+  "definitions": {
+    "NLQTrainingExample": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Natural language query"
+        },
+        "context": {
+          "type": "object",
+          "properties": {
+            "userId": {
+              "type": "string"
+            },
+            "userRole": {
+              "type": "string"
+            },
+            "currentObject": {
+              "type": "string",
+              "description": "Current object being viewed"
+            },
+            "currentRecordId": {
+              "type": "string",
+              "description": "Current record ID"
+            },
+            "conversationHistory": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "query": {
+                    "type": "string"
+                  },
+                  "timestamp": {
+                    "type": "string"
+                  },
+                  "intent": {
+                    "type": "string",
+                    "enum": [
+                      "select",
+                      "aggregate",
+                      "filter",
+                      "sort",
+                      "compare",
+                      "trend",
+                      "insight",
+                      "create",
+                      "update",
+                      "delete"
+                    ]
+                  }
+                },
+                "required": [
+                  "query",
+                  "timestamp"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "defaultLimit": {
+              "type": "integer",
+              "default": 100
+            },
+            "timezone": {
+              "type": "string",
+              "default": "UTC"
+            },
+            "locale": {
+              "type": "string",
+              "default": "en-US"
+            }
+          },
+          "additionalProperties": false
+        },
+        "expectedIntent": {
+          "type": "string",
+          "enum": [
+            "select",
+            "aggregate",
+            "filter",
+            "sort",
+            "compare",
+            "trend",
+            "insight",
+            "create",
+            "update",
+            "delete"
+          ]
+        },
+        "expectedObject": {
+          "type": "string"
+        },
+        "expectedAST": {
+          "description": "Expected ObjectQL AST"
+        },
+        "category": {
+          "type": "string",
+          "description": "Example category"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "notes": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "query",
+        "expectedIntent"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/OIDCConfig.json

@@ -4,16 +4,22 @@
     "OIDCConfig": {
       "type": "object",
       "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
         "issuer": {
           "type": "string",
           "format": "uri",
           "description": "OIDC Issuer URL (.well-known/openid-configuration)"
         },
         "clientId": {
-          "type": "string"
+          "type": "string",
+          "description": "OIDC client ID"
         },
         "clientSecret": {
-          "type": "string"
+          "type": "string",
+          "description": "OIDC client secret"
         },
         "scopes": {
           "type": "array",
@@ -24,7 +30,8 @@
             "openid",
             "profile",
             "email"
-          ]
+          ],
+          "description": "OIDC scopes"
         },
         "attributeMapping": {
           "type": "object",
@@ -32,6 +39,14 @@
             "type": "string"
           },
           "description": "Map IdP claims to User fields"
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Display name for the provider button"
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon URL or identifier"
         }
       },
       "required": [

package/json-schema/Organization.json

@@ -0,0 +1,52 @@
+{
+  "$ref": "#/definitions/Organization",
+  "definitions": {
+    "Organization": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique organization identifier"
+        },
+        "name": {
+          "type": "string",
+          "description": "Organization display name"
+        },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9_-]+$",
+          "description": "Unique URL-friendly slug (lowercase alphanumeric, hyphens, underscores)"
+        },
+        "logo": {
+          "type": "string",
+          "format": "uri",
+          "description": "Organization logo URL"
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Custom metadata"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Organization creation timestamp"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last update timestamp"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "slug",
+        "createdAt",
+        "updatedAt"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/PromptTemplate.json

@@ -0,0 +1,163 @@
+{
+  "$ref": "#/definitions/PromptTemplate",
+  "definitions": {
+    "PromptTemplate": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique template identifier"
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z_][a-z0-9_]*$",
+          "description": "Template name (snake_case)"
+        },
+        "label": {
+          "type": "string",
+          "description": "Display name"
+        },
+        "system": {
+          "type": "string",
+          "description": "System prompt"
+        },
+        "user": {
+          "type": "string",
+          "description": "User prompt template with variables"
+        },
+        "assistant": {
+          "type": "string",
+          "description": "Assistant message prefix"
+        },
+        "variables": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Variable name (e.g., \"user_name\", \"context\")"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "string",
+                  "number",
+                  "boolean",
+                  "object",
+                  "array"
+                ],
+                "default": "string"
+              },
+              "required": {
+                "type": "boolean",
+                "default": false
+              },
+              "defaultValue": {},
+              "description": {
+                "type": "string"
+              },
+              "validation": {
+                "type": "object",
+                "properties": {
+                  "minLength": {
+                    "type": "number"
+                  },
+                  "maxLength": {
+                    "type": "number"
+                  },
+                  "pattern": {
+                    "type": "string"
+                  },
+                  "enum": {
+                    "type": "array"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "name"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Template variables"
+        },
+        "modelId": {
+          "type": "string",
+          "description": "Recommended model ID"
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "maxTokens": {
+          "type": "number"
+        },
+        "topP": {
+          "type": "number"
+        },
+        "frequencyPenalty": {
+          "type": "number"
+        },
+        "presencePenalty": {
+          "type": "number"
+        },
+        "stopSequences": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "version": {
+          "type": "string",
+          "default": "1.0.0"
+        },
+        "description": {
+          "type": "string"
+        },
+        "category": {
+          "type": "string",
+          "description": "Template category (e.g., \"code_generation\", \"support\")"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "input": {
+                "type": "object",
+                "additionalProperties": {},
+                "description": "Example variable values"
+              },
+              "output": {
+                "type": "string",
+                "description": "Expected output"
+              }
+            },
+            "required": [
+              "input",
+              "output"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "label",
+        "user"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}