@openplanr/protocol 0.2.0

package/schemas/v1.2.0/guided-question.schema.json

@@ -0,0 +1,242 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.2.0/guided-question.schema.json",
+  "title": "OpenPlanr Protocol v1.2 guided question",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "schemaVersion",
+    "protocolVersion",
+    "questionId",
+    "questionVersion",
+    "type",
+    "label",
+    "explanation",
+    "required",
+    "sensitivity",
+    "persistence",
+    "valueSemantics"
+  ],
+  "properties": {
+    "kind": { "const": "guided-question" },
+    "schemaVersion": { "const": "1.0.0" },
+    "protocolVersion": { "const": "1.2.0" },
+    "questionId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,63}$" },
+    "questionVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "type": {
+      "type": "string",
+      "enum": [
+        "text",
+        "secret",
+        "single-select",
+        "multi-select",
+        "confirmation",
+        "path",
+        "repeated-text",
+        "informational"
+      ]
+    },
+    "label": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "explanation": { "type": "string", "minLength": 1, "maxLength": 1000 },
+    "required": { "type": "boolean" },
+    "sensitivity": { "type": "string", "enum": ["public", "internal", "sensitive"] },
+    "persistence": { "type": "string", "enum": ["none", "session"] },
+    "valueSemantics": { "type": "string", "enum": ["none", "suggestion", "default"] },
+    "suggestedValue": {
+      "oneOf": [
+        { "type": "string", "maxLength": 4096 },
+        { "type": "boolean" },
+        {
+          "type": "array",
+          "maxItems": 50,
+          "uniqueItems": true,
+          "items": { "type": "string", "maxLength": 256 }
+        }
+      ]
+    },
+    "suggestionReason": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "defaultValue": {
+      "oneOf": [
+        { "type": "string", "maxLength": 4096 },
+        { "type": "boolean" },
+        {
+          "type": "array",
+          "maxItems": 50,
+          "uniqueItems": true,
+          "items": { "type": "string", "maxLength": 256 }
+        }
+      ]
+    },
+    "defaultReason": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "choices": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "label"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+          "label": { "type": "string", "minLength": 1, "maxLength": 160 },
+          "description": { "type": "string", "minLength": 1, "maxLength": 500 },
+          "preselected": { "type": "boolean" }
+        }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minLength": { "type": "integer", "minimum": 0, "maximum": 4096 },
+        "maxLength": { "type": "integer", "minimum": 1, "maximum": 4096 },
+        "minItems": { "type": "integer", "minimum": 0, "maximum": 50 },
+        "maxItems": { "type": "integer", "minimum": 1, "maximum": 50 }
+      }
+    },
+    "visibleWhen": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["questionId", "operator"],
+        "properties": {
+          "questionId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,63}$" },
+          "operator": {
+            "type": "string",
+            "enum": ["equals", "not-equals", "contains", "not-contains", "answered", "not-answered"]
+          },
+          "value": {
+            "oneOf": [
+              { "type": "string", "maxLength": 256 },
+              { "type": "boolean" },
+              { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 256 } }
+            ]
+          }
+        },
+        "oneOf": [
+          {
+            "title": "Value comparison",
+            "required": ["value"],
+            "properties": {
+              "operator": { "enum": ["equals", "not-equals", "contains", "not-contains"] }
+            }
+          },
+          {
+            "title": "Presence comparison",
+            "properties": {
+              "operator": { "enum": ["answered", "not-answered"] }
+            },
+            "not": { "required": ["value"] }
+          }
+        ]
+      }
+    }
+  },
+  "allOf": [
+    {
+      "oneOf": [
+        {
+          "title": "Sensitive transient question",
+          "properties": {
+            "type": { "const": "secret" },
+            "sensitivity": { "const": "sensitive" },
+            "persistence": { "const": "none" },
+            "valueSemantics": { "const": "none" }
+          }
+        },
+        {
+          "title": "Non-sensitive question",
+          "properties": {
+            "type": {
+              "enum": [
+                "text",
+                "single-select",
+                "multi-select",
+                "confirmation",
+                "path",
+                "repeated-text",
+                "informational"
+              ]
+            },
+            "sensitivity": { "enum": ["public", "internal"] }
+          }
+        }
+      ]
+    },
+    {
+      "oneOf": [
+        {
+          "title": "Choice question",
+          "required": ["choices"],
+          "properties": { "type": { "enum": ["single-select", "multi-select"] } }
+        },
+        {
+          "title": "Non-choice question",
+          "properties": {
+            "type": {
+              "enum": ["text", "secret", "confirmation", "path", "repeated-text", "informational"]
+            }
+          },
+          "not": { "required": ["choices"] }
+        }
+      ]
+    },
+    {
+      "oneOf": [
+        {
+          "title": "No proposed value",
+          "properties": { "valueSemantics": { "const": "none" } },
+          "allOf": [
+            { "not": { "required": ["suggestedValue"] } },
+            { "not": { "required": ["defaultValue"] } }
+          ]
+        },
+        {
+          "title": "Suggested value",
+          "required": ["suggestedValue", "suggestionReason"],
+          "properties": { "valueSemantics": { "const": "suggestion" } },
+          "not": { "required": ["defaultValue"] }
+        },
+        {
+          "title": "Default value",
+          "required": ["defaultValue", "defaultReason"],
+          "properties": { "valueSemantics": { "const": "default" } },
+          "not": { "required": ["suggestedValue"] }
+        }
+      ]
+    },
+    {
+      "oneOf": [
+        {
+          "title": "Informational question",
+          "properties": {
+            "type": { "const": "informational" },
+            "required": { "const": false },
+            "persistence": { "const": "none" },
+            "valueSemantics": { "const": "none" }
+          }
+        },
+        {
+          "title": "Answerable question",
+          "properties": {
+            "type": {
+              "enum": [
+                "text",
+                "secret",
+                "single-select",
+                "multi-select",
+                "confirmation",
+                "path",
+                "repeated-text"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

package/schemas/v1.2.0/guided-questionnaire.schema.json

@@ -0,0 +1,278 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.2.0/guided-questionnaire.schema.json",
+  "title": "OpenPlanr Protocol v1.2 guided questionnaire",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "schemaVersion",
+    "protocolVersion",
+    "sessionId",
+    "digest",
+    "questionnaireVersion",
+    "command",
+    "projectIdentity",
+    "projectHead",
+    "configHead",
+    "adapter",
+    "stage",
+    "step",
+    "totalSteps",
+    "title",
+    "questions",
+    "createdAt",
+    "expiresAt"
+  ],
+  "properties": {
+    "kind": { "const": "guided-questionnaire" },
+    "schemaVersion": { "type": "string", "enum": ["1.0.0", "1.1.0"] },
+    "protocolVersion": { "const": "1.2.0" },
+    "sessionId": { "type": "string", "pattern": "^GIS-[A-Za-z0-9._-]{8,128}$" },
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "questionnaireVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "command": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,127}$" },
+    "projectIdentity": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "projectHead": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "configHead": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "adapter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtime", "version", "interaction"],
+      "properties": {
+        "runtime": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "version": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "interaction": { "type": "string", "enum": ["native", "chat", "terminal", "none"] }
+      }
+    },
+    "stage": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,63}$" },
+    "step": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "totalSteps": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "title": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "description": { "type": "string", "minLength": 1, "maxLength": 1000 },
+    "questions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": {
+        "$ref": "https://openplanr.dev/schemas/v1.2.0/guided-question.schema.json"
+      }
+    },
+    "submission": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "version",
+        "schema",
+        "transport",
+        "envelope"
+      ],
+      "properties": {
+        "kind": { "const": "guided-answer-submission" },
+        "version": { "const": "1.0.0" },
+        "schema": {
+          "const": "https://openplanr.dev/schemas/v1.2.0/guided-answer-envelope.schema.json"
+        },
+        "transport": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "mediaType", "encoding", "maxBytes", "argv"],
+          "properties": {
+            "kind": { "const": "stdin-json" },
+            "mediaType": { "const": "application/json" },
+            "encoding": { "const": "utf-8" },
+            "maxBytes": { "const": 65536 },
+            "argv": {
+              "type": "array",
+              "minItems": 7,
+              "maxItems": 7,
+              "prefixItems": [
+                { "const": "planr" },
+                { "const": "operate" },
+                { "const": "init" },
+                { "const": "--resume" },
+                { "type": "string", "pattern": "^GIS-[A-Za-z0-9._-]{8,128}$" },
+                { "const": "--stdin" },
+                { "const": "--json" }
+              ],
+              "items": false
+            }
+          }
+        },
+        "envelope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fixedFields", "dynamicFields"],
+          "properties": {
+            "fixedFields": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "kind",
+                "schemaVersion",
+                "protocolVersion",
+                "sessionId",
+                "questionnaireVersion",
+                "command",
+                "projectIdentity",
+                "projectHead",
+                "configHead",
+                "adapter"
+              ],
+              "properties": {
+                "kind": { "const": "guided-answer-envelope" },
+                "schemaVersion": { "const": "1.0.0" },
+                "protocolVersion": { "const": "1.2.0" },
+                "sessionId": {
+                  "type": "string",
+                  "pattern": "^GIS-[A-Za-z0-9._-]{8,128}$"
+                },
+                "questionnaireVersion": {
+                  "type": "string",
+                  "pattern": "^\\d+\\.\\d+\\.\\d+$"
+                },
+                "command": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9.-]{0,127}$"
+                },
+                "projectIdentity": {
+                  "type": "string",
+                  "pattern": "^sha256:[a-f0-9]{64}$"
+                },
+                "projectHead": {
+                  "type": "string",
+                  "pattern": "^sha256:[a-f0-9]{64}$"
+                },
+                "configHead": {
+                  "type": "string",
+                  "pattern": "^sha256:[a-f0-9]{64}$"
+                },
+                "adapter": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["runtime", "version", "interaction"],
+                  "properties": {
+                    "runtime": {
+                      "type": "string",
+                      "pattern": "^[a-z][a-z0-9-]*$"
+                    },
+                    "version": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 64
+                    },
+                    "interaction": {
+                      "type": "string",
+                      "enum": ["native", "chat", "terminal", "none"]
+                    }
+                  }
+                }
+              }
+            },
+            "dynamicFields": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["questionnaireDigest", "submittedAt", "answers"],
+              "properties": {
+                "questionnaireDigest": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["source", "pointer"],
+                  "properties": {
+                    "source": { "const": "questionnaire" },
+                    "pointer": { "const": "/digest" }
+                  }
+                },
+                "submittedAt": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["source", "format"],
+                  "properties": {
+                    "source": { "const": "runtime-clock" },
+                    "format": { "const": "date-time" }
+                  }
+                },
+                "answers": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "source",
+                    "copyFields",
+                    "omitUnansweredOptional",
+                    "items"
+                  ],
+                  "properties": {
+                    "source": { "const": "chosen-values-by-question-id" },
+                    "copyFields": {
+                      "type": "array",
+                      "minItems": 3,
+                      "maxItems": 3,
+                      "prefixItems": [
+                        { "const": "questionId" },
+                        { "const": "questionVersion" },
+                        { "const": "sensitivity" }
+                      ],
+                      "items": false
+                    },
+                    "omitUnansweredOptional": { "const": true },
+                    "items": {
+                      "type": "array",
+                      "minItems": 0,
+                      "maxItems": 50,
+                      "uniqueItems": true,
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "required": [
+                          "questionId",
+                          "questionVersion",
+                          "sensitivity",
+                          "required",
+                          "valueType"
+                        ],
+                        "properties": {
+                          "questionId": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9.-]{0,63}$"
+                          },
+                          "questionVersion": {
+                            "type": "string",
+                            "pattern": "^\\d+\\.\\d+\\.\\d+$"
+                          },
+                          "sensitivity": {
+                            "type": "string",
+                            "enum": ["public", "internal", "sensitive"]
+                          },
+                          "required": { "type": "boolean" },
+                          "valueType": {
+                            "type": "string",
+                            "enum": ["string", "boolean", "string-array"]
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" }
+  },
+  "oneOf": [
+    {
+      "title": "Original questionnaire",
+      "properties": { "schemaVersion": { "const": "1.0.0" } },
+      "not": { "required": ["submission"] }
+    },
+    {
+      "title": "Self-describing questionnaire",
+      "properties": { "schemaVersion": { "const": "1.1.0" } },
+      "required": ["submission"]
+    }
+  ]
+}

package/schemas/v1.2.0/guided-session.schema.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.2.0/guided-session.schema.json",
+  "title": "OpenPlanr Protocol v1.2 guided interaction session",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "schemaVersion",
+    "protocolVersion",
+    "sessionId",
+    "state",
+    "command",
+    "projectIdentity",
+    "projectHead",
+    "configHead",
+    "questionnaireDigest",
+    "questionnaireVersion",
+    "adapter",
+    "persistedAnswers",
+    "createdAt",
+    "updatedAt",
+    "expiresAt"
+  ],
+  "properties": {
+    "kind": { "const": "guided-session" },
+    "schemaVersion": { "const": "1.0.0" },
+    "protocolVersion": { "const": "1.2.0" },
+    "sessionId": { "type": "string", "pattern": "^GIS-[A-Za-z0-9._-]{8,128}$" },
+    "state": {
+      "type": "string",
+      "enum": [
+        "created",
+        "awaiting-input",
+        "preview-ready",
+        "confirmed",
+        "applied",
+        "cancelled",
+        "expired",
+        "stale",
+        "invalid"
+      ]
+    },
+    "command": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,127}$" },
+    "projectIdentity": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "projectHead": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "configHead": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "questionnaireDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "questionnaireVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "adapter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtime", "version", "interaction"],
+      "properties": {
+        "runtime": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "version": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "interaction": { "type": "string", "enum": ["native", "chat", "terminal", "none"] }
+      }
+    },
+    "persistedAnswers": {
+      "type": "array",
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["questionId", "questionVersion", "sensitivity", "value"],
+        "properties": {
+          "questionId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,63}$" },
+          "questionVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+          "sensitivity": { "type": "string", "enum": ["public", "internal"] },
+          "value": {
+            "oneOf": [
+              { "type": "string", "maxLength": 4096 },
+              { "type": "boolean" },
+              {
+                "type": "array",
+                "maxItems": 50,
+                "uniqueItems": true,
+                "items": { "type": "string", "maxLength": 4096 }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "previewDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "confirmationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "confirmedAt": { "type": "string", "format": "date-time" },
+    "appliedAt": { "type": "string", "format": "date-time" },
+    "terminalReason": { "type": "string", "minLength": 1, "maxLength": 500 }
+  },
+  "oneOf": [
+    {
+      "title": "Created session",
+      "properties": { "state": { "const": "created" } }
+    },
+    {
+      "title": "Awaiting input",
+      "properties": { "state": { "const": "awaiting-input" } }
+    },
+    {
+      "title": "Preview ready",
+      "required": ["previewDigest"],
+      "properties": { "state": { "const": "preview-ready" } }
+    },
+    {
+      "title": "Confirmed session",
+      "required": ["previewDigest", "confirmationDigest", "confirmedAt"],
+      "properties": { "state": { "const": "confirmed" } }
+    },
+    {
+      "title": "Applied session",
+      "required": ["previewDigest", "confirmationDigest", "confirmedAt", "appliedAt"],
+      "properties": { "state": { "const": "applied" } }
+    },
+    {
+      "title": "Cancelled session",
+      "required": ["terminalReason"],
+      "properties": { "state": { "const": "cancelled" } }
+    },
+    {
+      "title": "Expired session",
+      "required": ["terminalReason"],
+      "properties": { "state": { "const": "expired" } }
+    },
+    {
+      "title": "Stale session",
+      "required": ["terminalReason"],
+      "properties": { "state": { "const": "stale" } }
+    },
+    {
+      "title": "Invalid session",
+      "required": ["terminalReason"],
+      "properties": { "state": { "const": "invalid" } }
+    }
+  ]
+}