kalup 0.1.0

package/dist/schemas/ir-1.schema.json

@@ -0,0 +1,379 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kalup.dev/schemas/ir-1.schema.json",
+  "title": "Kalup IR, version 1",
+  "description": "What a Kalup project's config files mean, derived by `kalup ir`, or what a portal holds, captured by `kalup snapshot` with an observation block. Change inside a version is additive and readers keep unknown fields, so the document and each resource accept fields this schema does not list. Below a resource everything is closed except `x` and the definition of a resource type this schema does not describe, which stays open until a later ir/1 release describes that type.",
+  "type": "object",
+  "required": ["irVersion", "project", "generator", "resources", "targets", "tombstones"],
+  "properties": {
+    "irVersion": { "const": 1 },
+    "project": { "type": "string" },
+    "generator": {
+      "type": "object",
+      "required": ["name", "version", "frontend"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "frontend": { "enum": ["ts", "portal"] }
+      },
+      "additionalProperties": false
+    },
+    "resources": {
+      "type": "object",
+      "patternProperties": { "^[a-z]+:\\S+$": { "$ref": "#/$defs/resource" } },
+      "additionalProperties": false
+    },
+    "targets": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/target" }
+    },
+    "tombstones": {
+      "type": "object",
+      "patternProperties": { "^[a-z]+:\\S+$": { "$ref": "#/$defs/tombstone" } },
+      "additionalProperties": false
+    },
+    "observation": { "$ref": "#/$defs/observation" },
+    "x": { "type": "object" }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["generator"],
+        "properties": { "generator": { "required": ["frontend"], "properties": { "frontend": { "const": "portal" } } } }
+      },
+      "then": { "required": ["observation"] }
+    }
+  ],
+  "$defs": {
+    "address": {
+      "description": "'<type>:<path>', for example property:companies/billing_status.",
+      "type": "string",
+      "pattern": "^[a-z]+:\\S+$"
+    },
+    "ref": {
+      "description": "A logical reference, allowed anywhere inside a definition where HubSpot wants an ID.",
+      "type": "object",
+      "required": ["$ref"],
+      "properties": { "$ref": { "$ref": "#/$defs/address" } },
+      "additionalProperties": false
+    },
+    "resource": {
+      "type": "object",
+      "required": ["type", "managed"],
+      "properties": {
+        "type": { "type": "string" },
+        "managed": { "type": "boolean" },
+        "definition": { "type": "object" },
+        "lookup": { "type": "object", "additionalProperties": { "type": "string" } },
+        "binding": { "$ref": "#/$defs/binding" },
+        "lifecycle": { "$ref": "#/$defs/lifecycle" },
+        "provenance": { "$ref": "#/$defs/provenance" },
+        "x": { "type": "object" }
+      },
+      "allOf": [
+        {
+          "if": { "required": ["managed"], "properties": { "managed": { "const": true } } },
+          "then": { "required": ["definition"] }
+        },
+        {
+          "if": { "required": ["type"], "properties": { "type": { "const": "property" } } },
+          "then": { "properties": { "definition": { "$ref": "#/$defs/propertyFields" } } }
+        },
+        {
+          "if": {
+            "required": ["type", "managed"],
+            "properties": { "type": { "const": "property" }, "managed": { "const": true } }
+          },
+          "then": { "properties": { "definition": { "required": ["label", "group", "type", "fieldType"] } } }
+        },
+        {
+          "if": { "required": ["type"], "properties": { "type": { "const": "group" } } },
+          "then": { "properties": { "definition": { "$ref": "#/$defs/groupDefinition" } } }
+        },
+        {
+          "if": { "required": ["type"], "properties": { "type": { "const": "object" } } },
+          "then": { "properties": { "definition": { "$ref": "#/$defs/objectDefinition" } } }
+        }
+      ]
+    },
+    "propertyFields": {
+      "description": "A property definition in HubSpot terms. A managed property needs label, group, type and fieldType; an unmanaged one may carry any subset, such as the options of a HubSpot-defined enumeration.",
+      "type": "object",
+      "properties": {
+        "label": { "type": "string" },
+        "group": { "$ref": "#/$defs/ref" },
+        "type": { "enum": ["string", "number", "bool", "date", "datetime", "enumeration"] },
+        "fieldType": {
+          "enum": [
+            "text",
+            "textarea",
+            "file",
+            "phonenumber",
+            "number",
+            "booleancheckbox",
+            "select",
+            "radio",
+            "checkbox",
+            "date"
+          ]
+        },
+        "description": { "type": "string" },
+        "options": { "type": "array", "items": { "$ref": "#/$defs/option" } },
+        "hasUniqueValue": { "type": "boolean" },
+        "formField": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "option": {
+      "description": "One enumeration option. Array index is display order. The app alias lives in binding.aliases, never here.",
+      "type": "object",
+      "required": ["value", "label"],
+      "properties": {
+        "value": { "type": "string" },
+        "label": { "type": "string" },
+        "hidden": { "type": "boolean" },
+        "description": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "groupDefinition": {
+      "type": "object",
+      "required": ["label"],
+      "properties": { "label": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "objectDefinition": {
+      "description": "A custom object schema. Its properties and groups are resources of their own.",
+      "type": "object",
+      "required": ["labels"],
+      "properties": {
+        "labels": {
+          "type": "object",
+          "required": ["singular", "plural"],
+          "properties": { "singular": { "type": "string" }, "plural": { "type": "string" } },
+          "additionalProperties": false
+        },
+        "primaryDisplayProperty": { "type": "string" },
+        "requiredProperties": { "type": "array", "items": { "type": "string" } },
+        "searchableProperties": { "type": "array", "items": { "type": "string" } },
+        "secondaryDisplayProperties": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "binding": {
+      "description": "App terms, filled in by the loader. key and codec for properties, export for objects.",
+      "type": "object",
+      "properties": {
+        "key": { "type": "string" },
+        "codec": {
+          "enum": ["string", "number", "boolean", "date", "datetime", "enum", "multiEnum", "stringArray", "json"]
+        },
+        "aliases": { "type": "object", "additionalProperties": { "type": "string" } },
+        "required": { "type": "boolean" },
+        "readonly": { "type": "boolean" },
+        "strict": { "type": "boolean" },
+        "export": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "lifecycle": {
+      "type": "object",
+      "required": ["options"],
+      "properties": {
+        "options": { "enum": ["additive", "exact"] },
+        "removedOptions": { "type": "array", "items": { "type": "string" } },
+        "ignoreChanges": { "type": "array", "items": { "type": "string" } },
+        "preventDestroy": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "provenance": {
+      "description": "Merged from kalup/blueprints.lock.json by the loader. Absent means authored by hand.",
+      "type": "object",
+      "required": ["blueprint", "version", "sourceAddress", "prefix", "hash"],
+      "properties": {
+        "blueprint": { "type": "string" },
+        "version": { "type": "string" },
+        "sourceAddress": { "$ref": "#/$defs/address" },
+        "prefix": { "type": "string" },
+        "hash": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "target": {
+      "description": "One named portal. Credentials never enter the IR.",
+      "type": "object",
+      "required": ["portalId"],
+      "properties": {
+        "portalId": { "type": "integer", "minimum": 1 },
+        "protected": { "type": "boolean" },
+        "drift": { "enum": ["hold", "overwrite"] },
+        "adopt": {
+          "description": "What a plan does with a unit that has no base and differs. Default hold.",
+          "enum": ["hold", "overwrite"]
+        },
+        "allowDestroy": {
+          "description": "Whether a destroy tombstone or a takeover removal may delete in this portal. Default false.",
+          "type": "boolean"
+        },
+        "yesLimit": {
+          "description": "The most writes, adoptions and releases one --yes covers; 0 turns --yes off. Default 25.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1000
+        },
+        "overrides": {
+          "type": "object",
+          "patternProperties": { "^[a-z]+:\\S+$": { "$ref": "#/$defs/override" } },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "override": {
+      "type": "object",
+      "properties": {
+        "skip": { "const": true },
+        "name": { "type": "string" },
+        "definition": { "type": "object" },
+        "lookup": { "type": "object", "additionalProperties": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "observation": {
+      "description": "What a snapshot read: the target, when, and how completely. A portal-frontend document requires it. observedAt is the one timestamp an ir/1 document carries.",
+      "type": "object",
+      "required": ["target", "observedAt", "coverage"],
+      "properties": {
+        "target": {
+          "type": "object",
+          "required": ["name", "portalId"],
+          "properties": { "name": { "type": "string" }, "portalId": { "type": "integer", "minimum": 1 } },
+          "additionalProperties": false
+        },
+        "observedAt": {
+          "description": "ISO 8601 in UTC, as Date.prototype.toISOString writes it.",
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?Z$"
+        },
+        "coverage": { "$ref": "#/$defs/coverage" }
+      },
+      "additionalProperties": false
+    },
+    "coverage": {
+      "description": "What the read covered. Only a complete read proves that a resource is absent.",
+      "type": "object",
+      "required": ["complete", "objects", "otherObjects", "notCaptured"],
+      "properties": {
+        "complete": { "type": "boolean" },
+        "objects": {
+          "description": "One entry per config object key.",
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/objectCoverage" }
+        },
+        "otherObjects": {
+          "description": "Custom objects in the portal that config does not name, or unknown when the schemas list was not read.",
+          "type": ["array", "string"],
+          "items": { "type": "string" },
+          "if": { "type": "string" },
+          "then": { "const": "unknown" }
+        },
+        "notCaptured": {
+          "description": "Documented response fields Kalup does not capture, per resource type.",
+          "type": "object",
+          "required": ["property", "group", "object"],
+          "properties": {
+            "property": { "type": "array", "items": { "type": "string" } },
+            "group": { "type": "array", "items": { "type": "string" } },
+            "object": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "objectCoverage": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["read", "unreadable", "absent", "excluded"] },
+        "missingScope": { "description": "Unreadable only.", "type": "string" },
+        "issue": { "description": "Unreadable only.", "type": "string" },
+        "objectTypeId": { "description": "A custom object that exists.", "type": "string" },
+        "outOfScope": {
+          "description": "Present properties outside the pull scope that config does not name.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "shadowed": {
+          "description": "Portal names equal to the local name of a renamed address, so not reported at it.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "unaddressable": {
+          "description": "Present properties config names that are in a group whose name no address can hold, so not captured. What they hold is unknown.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "unsupported": { "type": "array", "items": { "$ref": "#/$defs/unsupportedProperty" } },
+        "unsupportedSchema": {
+          "description": "A custom object HubSpot returned without a singular or plural label, its fields as returned. It is present but not a resource.",
+          "type": "object",
+          "required": ["labels"],
+          "properties": {
+            "labels": {
+              "type": "object",
+              "properties": { "singular": { "type": "string" }, "plural": { "type": "string" } },
+              "additionalProperties": false
+            },
+            "primaryDisplayProperty": { "type": "string" },
+            "requiredProperties": { "type": "array", "items": { "type": "string" } },
+            "searchableProperties": { "type": "array", "items": { "type": "string" } },
+            "secondaryDisplayProperties": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        },
+        "excluded": {
+          "description": "Addresses a skip override leaves out.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/address" }
+        },
+        "renamed": {
+          "description": "Addresses a name override points at another portal name.",
+          "type": "object",
+          "patternProperties": { "^[a-z]+:\\S+$": { "type": "string" } },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "unsupportedProperty": {
+      "description": "A present property Kalup does not write: no builder carries its type or fieldType, or HubSpot fills its options (owner or externalOptions). It is compared like any property but is not a resource.",
+      "type": "object",
+      "required": ["name", "type", "fieldType", "label", "group", "hubspotDefined"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "fieldType": { "type": "string" },
+        "label": { "type": "string" },
+        "group": { "$ref": "#/$defs/ref" },
+        "description": { "type": "string" },
+        "options": { "type": "array", "items": { "$ref": "#/$defs/option" } },
+        "hubspotDefined": { "type": "boolean" },
+        "externalOptions": { "type": "boolean" },
+        "referencedObjectType": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "tombstone": {
+      "description": "Written by `kalup rm`. destroy archives or deletes in the portal; release stops managing and leaves it.",
+      "type": "object",
+      "required": ["action"],
+      "properties": {
+        "action": { "enum": ["destroy", "release"] },
+        "reason": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}