Initial push

hubzilla/addon/vs01/contracts/spool-v1.json

@@ -0,0 +1,87 @@
+{
+  "_meta": {
+    "contract_version": "1.0",
+    "addon": "vs01",
+    "purpose": "Defines the spool envelope that vs01 produces and POSTs to the orchestrator receiver for every VS form submission.",
+    "created": "2026-06",
+    "supersedes": null,
+    "notes": "When the payload structure changes, increment to spool-v2.json. This file is never deleted — it documents what the orchestrator must remain able to consume."
+  },
+
+  "_header": {
+    "addon": {
+      "type": "string",
+      "value": "vs01",
+      "description": "Identifies the originating addon. Always 'vs01' for this contract."
+    },
+    "contract_version": {
+      "type": "string",
+      "value": "1.0",
+      "description": "The spool contract version. Must match this filename's version suffix."
+    },
+    "vs_code": {
+      "type": "string",
+      "format": "VS-NN",
+      "example": "VS-01",
+      "description": "The Vital Sign code being submitted. Must match a key in the loaded schemas."
+    },
+    "perspective": {
+      "type": "string",
+      "enum": ["homeowner", "professional", "public_record"],
+      "description": "The perspective slot being submitted. Determined by the submitter's access state."
+    },
+    "association_slug": {
+      "type": "string",
+      "description": "The URL slug of the association. Matches the key in config.json associations object."
+    },
+    "association_channel_id": {
+      "type": "string",
+      "description": "The Hubzilla channel ID of the association channel. Integer stored as string."
+    },
+    "submitted_at": {
+      "type": "string",
+      "format": "ISO 8601",
+      "example": "2026-06-15T14:32:00+00:00",
+      "description": "Timestamp of submission in ISO 8601 format."
+    },
+    "standing": {
+      "type": "string",
+      "enum": ["public", "participant", "professional", "operator"],
+      "description": "The access state of the submitter at the time of submission."
+    }
+  },
+
+  "_payload": {
+    "fields": {
+      "type": "object",
+      "description": "Keyed object of submitted field values. Keys match the field id values defined in the VS schema for the submitted perspective. Values are strings. Multiselect fields are JSON-encoded arrays.",
+      "example": {
+        "ho_claimed_type": "condominium",
+        "ho_claimed_source": "governing_documents",
+        "ho_type_denied_in_writing": "false",
+        "ho_type_inconsistent": "true",
+        "ho_inconsistency_detail": "The Declaration says Condominium. The attorney letter of March 2024 refers to it as a Master Association.",
+        "ho_account": "I have lived here for six years and have never been given a straight answer about what kind of association this is."
+      }
+    }
+  },
+
+  "_example_envelope": {
+    "addon": "vs01",
+    "contract_version": "1.0",
+    "vs_code": "VS-01",
+    "perspective": "homeowner",
+    "association_slug": "elm-court-condominiums",
+    "association_channel_id": "42",
+    "submitted_at": "2026-06-15T14:32:00+00:00",
+    "standing": "participant",
+    "fields": {
+      "ho_claimed_type": "condominium",
+      "ho_claimed_source": "governing_documents",
+      "ho_type_denied_in_writing": "false",
+      "ho_type_inconsistent": "false",
+      "ho_inconsistency_detail": "",
+      "ho_account": "The Declaration provided at closing identifies this as a condominium association under 765 ILCS 605."
+    }
+  }
+}