@sakibcoolz/core 0.1.2 → 0.2.0

package/schema/fixtures/validator-only/view-unknown-component.scene.json

@@ -0,0 +1,143 @@
+{
+  "schemaVersion": 4,
+  "documentType": "industrial.scene",
+  "units": "m",
+  "components": [
+    {
+      "id": "T1",
+      "type": "tank",
+      "position": {
+        "x": 0,
+        "y": 0.5,
+        "z": 0
+      },
+      "rotation": {
+        "x": 0,
+        "y": 0,
+        "z": 0,
+        "w": 1
+      },
+      "scale": {
+        "x": 1,
+        "y": 1,
+        "z": 1
+      },
+      "properties": {}
+    },
+    {
+      "id": "V1",
+      "type": "valve",
+      "position": {
+        "x": 2,
+        "y": 0.5,
+        "z": 0
+      },
+      "rotation": {
+        "x": 0,
+        "y": 0,
+        "z": 0,
+        "w": 1
+      },
+      "scale": {
+        "x": 1,
+        "y": 1,
+        "z": 1
+      },
+      "properties": {}
+    }
+  ],
+  "connections": [
+    {
+      "id": "c",
+      "from": {
+        "instanceId": "T1",
+        "portId": "outlet"
+      },
+      "to": {
+        "instanceId": "V1",
+        "portId": "in"
+      }
+    }
+  ],
+  "associations": [
+    {
+      "id": "a1",
+      "relationship": "feeds",
+      "from": "T1",
+      "to": "V1",
+      "properties": {
+        "note": "gravity feed"
+      }
+    },
+    {
+      "id": "a2",
+      "relationship": "com.example.supervises",
+      "from": "V1",
+      "to": "T1"
+    }
+  ],
+  "views": {
+    "process": {
+      "symbols": {
+        "T1": {
+          "x": 40,
+          "y": 120
+        },
+        "V1": {
+          "x": 160,
+          "y": 120,
+          "rotation": 90
+        },
+        "P9": {
+          "x": 0,
+          "y": 0
+        }
+      },
+      "routes": {
+        "c": {
+          "points": [
+            [
+              60,
+              120
+            ],
+            [
+              110,
+              120
+            ],
+            [
+              110,
+              130
+            ],
+            [
+              150,
+              130
+            ]
+          ]
+        }
+      }
+    },
+    "electrical": {
+      "symbols": {
+        "V1": {
+          "x": 0,
+          "y": 0,
+          "hidden": true
+        }
+      },
+      "routes": {
+        "a1": {
+          "points": [
+            [
+              0,
+              0
+            ],
+            [
+              10,
+              0
+            ]
+          ]
+        }
+      }
+    }
+  }
+}

package/schema/industrial-scene.v4.schema.json

@@ -0,0 +1,365 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sakibcoolz:3d-scada-sdk:industrial-scene:4",
+  "title": "Industrial scene document, schema version 4",
+  "description": "Structure of a scene file written by @sakibcoolz/core serializeScene (ADR-0021). The TypeScript validateScene is authoritative and also checks what JSON Schema cannot express: unit-length rotations, references between components, ports, connections and bindings, port compatibility and occupancy, scale policy, assembly cycles, units per quantity, credential-like key names (SECRET_FIELD), and the extension depth (16) and value (10,000 per document) budgets. Anything validateScene accepts with the default limits (defaultSceneLimits) also passes this schema; hosts that raise the limits must not rely on it. Older files (versions 1 to 3) are accepted by validateScene and migrated; this schema describes version 4 only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "documentType", "units", "components", "connections"],
+  "properties": {
+    "schemaVersion": { "const": 4 },
+    "documentType": { "const": "industrial.scene" },
+    "units": { "const": "m", "description": "Lengths are metres; right-handed, Y-up." },
+    "project": { "$ref": "#/$defs/project" },
+    "components": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/$defs/component" } },
+    "connections": { "type": "array", "maxItems": 20000, "items": { "$ref": "#/$defs/connection" } },
+    "associations": {
+      "description": "Port-less logical links between components, such as a PLC that controls a drive (ADR-0023). Never drawn as wiring.",
+      "type": "array",
+      "maxItems": 20000,
+      "items": { "$ref": "#/$defs/association" }
+    },
+    "dataSources": {
+      "description": "Where values come from: a PLC, drive or gateway the host reaches (ADR-0024). Never credentials.",
+      "type": "array",
+      "maxItems": 1000,
+      "items": { "$ref": "#/$defs/dataSource" }
+    },
+    "runtimeVariables": {
+      "description": "Typed tags: data type, unit, read-only access and a protocol-typed address (ADR-0024). Values arrive as observations, never in the document.",
+      "type": "array",
+      "maxItems": 20000,
+      "items": { "$ref": "#/$defs/runtimeVariable" }
+    },
+    "tagBindings": { "type": "array", "maxItems": 20000, "items": { "$ref": "#/$defs/tagBinding" } },
+    "underlay": { "$ref": "#/$defs/underlay" },
+    "views": {
+      "description": "2D layouts per view (ADR-0026): symbol placements by component id and routes by connection or association id, in drawing units (1 mm, x right, y down). Layout only; the model stays in components and connections.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "process": { "$ref": "#/$defs/viewLayout" }, "electrical": { "$ref": "#/$defs/viewLayout" } }
+    },
+    "extensions": { "$ref": "#/$defs/extensions" }
+  },
+  "$defs": {
+    "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "text": { "type": "string", "minLength": 1, "maxLength": 1024 },
+    "vector3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "z"],
+      "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }
+    },
+    "positiveVector3": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "z"],
+      "properties": {
+        "x": { "type": "number", "exclusiveMinimum": 0 },
+        "y": { "type": "number", "exclusiveMinimum": 0 },
+        "z": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    },
+    "quaternion": {
+      "description": "Unit quaternion (length 1 within 1e-6, checked by validateScene).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "z", "w"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "z": { "type": "number" },
+        "w": { "type": "number" }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "$ref": "#/$defs/text" },
+        "revision": { "$ref": "#/$defs/text" },
+        "description": { "$ref": "#/$defs/text" }
+      }
+    },
+    "componentKind": {
+      "description": "A built-in kind, or a namespaced host type such as com.example.press (ADR-0022). Whether a host type is registered is checked by validateScene (resolveType).",
+      "anyOf": [
+        { "enum": ["tank", "conicalTank", "horizontalTank", "sphericalTank", "pool", "pipe", "elbow", "tee", "valve", "reducer", "coupler", "pump", "sensor", "motor"] },
+        { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$" }
+      ]
+    },
+    "component": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "position", "rotation", "scale", "properties"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "$ref": "#/$defs/text" },
+        "type": { "$ref": "#/$defs/componentKind" },
+        "typeVersion": { "$ref": "#/$defs/text" },
+        "manufacturer": { "$ref": "#/$defs/text" },
+        "model": { "$ref": "#/$defs/text" },
+        "parentId": { "$ref": "#/$defs/id", "description": "Assembly parent (ADR-0008)." },
+        "position": { "$ref": "#/$defs/vector3", "description": "Metres, world space." },
+        "rotation": { "$ref": "#/$defs/quaternion" },
+        "scale": { "$ref": "#/$defs/positiveVector3", "description": "Components with ports keep 1, 1, 1 (checked by validateScene)." },
+        "properties": {
+          "description": "Engineering and display properties; the component definition validates names and ranges.",
+          "type": "object",
+          "maxProperties": 64,
+          "additionalProperties": { "anyOf": [{ "type": "string", "maxLength": 1024 }, { "type": "number" }, { "type": "boolean" }] }
+        },
+        "labels": {
+          "description": "Identification and metadata tags. Never credentials and never live values.",
+          "type": "object",
+          "maxProperties": 64,
+          "propertyNames": { "minLength": 1, "maxLength": 128 },
+          "additionalProperties": { "type": "string", "maxLength": 1024 }
+        },
+        "extensions": { "$ref": "#/$defs/extensions" }
+      }
+    },
+    "endpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instanceId", "portId"],
+      "properties": { "instanceId": { "$ref": "#/$defs/id" }, "portId": { "$ref": "#/$defs/id" } }
+    },
+    "relationship": {
+      "description": "A built-in relationship, or a namespaced host relationship such as com.example.supervises (ADR-0023).",
+      "anyOf": [
+        { "enum": ["controls", "drives", "measures", "feeds", "communicates", "wired", "associated"] },
+        { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$" }
+      ]
+    },
+    "edgeProperties": {
+      "description": "Edge data such as cable type, cross-section or length (ADR-0023). Credential-like names are rejected by validateScene.",
+      "type": "object",
+      "maxProperties": 64,
+      "additionalProperties": { "anyOf": [{ "type": "string", "maxLength": 1024 }, { "type": "number" }, { "type": "boolean" }] }
+    },
+    "connection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "from", "to"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "domain": {
+          "description": "The ports' domain (ADR-0023); validateScene checks that it matches them. Derived from the ports when absent.",
+          "enum": ["fluid", "mechanical", "power", "signal", "network", "electrical"]
+        },
+        "relationship": { "$ref": "#/$defs/relationship" },
+        "from": { "$ref": "#/$defs/endpoint" },
+        "to": { "$ref": "#/$defs/endpoint" },
+        "properties": { "$ref": "#/$defs/edgeProperties" }
+      }
+    },
+    "dataSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "protocol"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "$ref": "#/$defs/text" },
+        "protocol": {
+          "description": "A built-in protocol, or a namespaced host protocol such as com.vendor.bus.",
+          "anyOf": [
+            { "enum": ["opcua", "modbus-tcp", "modbus-rtu", "host"] },
+            { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$" }
+          ]
+        },
+        "deviceId": { "$ref": "#/$defs/id" },
+        "endpointRef": { "description": "Opaque reference the host resolves. validateScene rejects URLs with user info.", "$ref": "#/$defs/text" },
+        "properties": { "$ref": "#/$defs/edgeProperties" }
+      }
+    },
+    "runtimeVariable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "dataType", "access"],
+      "properties": {
+        "id": { "description": "The tag id observations and bindings carry.", "$ref": "#/$defs/id" },
+        "name": { "$ref": "#/$defs/text" },
+        "componentId": { "$ref": "#/$defs/id" },
+        "dataType": { "enum": ["bool", "int16", "uint16", "int32", "uint32", "float32", "float64", "string"] },
+        "unit": { "type": "string", "maxLength": 32 },
+        "access": { "description": "\"readWrite\" allows a confirmed command request to the host (ADR-0029); the SDK never writes.", "enum": ["read", "readWrite"] },
+        "source": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["dataSourceId"],
+          "properties": {
+            "dataSourceId": { "$ref": "#/$defs/id" },
+            "variable": { "$ref": "#/$defs/text" },
+            "address": {
+              "description": "Typed by the data source's protocol (OPC UA nodeId, Modbus area/address/unitId…); validateScene checks it against that protocol.",
+              "type": "object"
+            }
+          }
+        },
+        "scaling": {
+          "description": "How the host converts raw values; descriptive only.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "rawMin", "rawMax", "min", "max"],
+          "properties": {
+            "kind": { "const": "linear" },
+            "rawMin": { "type": "number" },
+            "rawMax": { "type": "number" },
+            "min": { "type": "number" },
+            "max": { "type": "number" }
+          }
+        },
+        "command": {
+          "description": "Limits of a readWrite variable (ADR-0029); the host's gateway must enforce them too. validateScene also checks min < max and that both fit the data type.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min": { "type": "number" },
+            "max": { "type": "number" },
+            "step": { "type": "number", "exclusiveMinimum": 0 },
+            "confirm": { "$ref": "#/$defs/text" }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "required": ["access"], "properties": { "access": { "const": "readWrite" } } },
+          "then": { "required": ["command", "source"], "properties": { "command": true, "source": true, "dataType": { "not": { "const": "string" } } } },
+          "else": { "not": { "required": ["command"], "properties": { "command": true } } }
+        },
+        {
+          "if": { "required": ["access", "dataType"], "properties": { "access": { "const": "readWrite" }, "dataType": { "not": { "const": "bool" } } } },
+          "then": { "properties": { "command": { "type": "object", "required": ["min", "max"], "properties": { "min": true, "max": true } } } }
+        },
+        {
+          "if": { "required": ["dataType"], "properties": { "dataType": { "const": "bool" } } },
+          "then": { "properties": { "command": { "not": { "anyOf": [{ "type": "object", "required": ["min"], "properties": { "min": true } }, { "type": "object", "required": ["max"], "properties": { "max": true } }] } } } }
+        }
+      ]
+    },
+    "association": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "relationship", "from", "to"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "relationship": { "$ref": "#/$defs/relationship" },
+        "from": { "$ref": "#/$defs/id" },
+        "to": { "$ref": "#/$defs/id" },
+        "properties": { "$ref": "#/$defs/edgeProperties" }
+      }
+    },
+    "tagBinding": {
+      "description": "Authored link from a host tag to a component property or a connection's flow (ADR-0006).",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "tagId", "kind", "instanceId", "property"],
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "tagId": { "$ref": "#/$defs/id" },
+            "kind": { "const": "property" },
+            "instanceId": { "$ref": "#/$defs/id" },
+            "property": { "$ref": "#/$defs/id" },
+            "unit": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "tagId", "kind", "connectionId"],
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "tagId": { "$ref": "#/$defs/id" },
+            "kind": { "const": "flow" },
+            "connectionId": { "$ref": "#/$defs/id" },
+            "unit": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "viewCoordinate": { "type": "number", "minimum": -1000000, "maximum": 1000000 },
+    "viewLayout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "symbols": {
+          "type": "object",
+          "maxProperties": 10000,
+          "propertyNames": { "$ref": "#/$defs/id" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x", "y"],
+            "properties": {
+              "x": { "$ref": "#/$defs/viewCoordinate" },
+              "y": { "$ref": "#/$defs/viewCoordinate" },
+              "rotation": { "enum": [0, 90, 180, 270] },
+              "hidden": { "const": true }
+            }
+          }
+        },
+        "routes": {
+          "type": "object",
+          "maxProperties": 40000,
+          "propertyNames": { "$ref": "#/$defs/id" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["points"],
+            "properties": {
+              "points": {
+                "type": "array",
+                "minItems": 2,
+                "maxItems": 1000,
+                "items": { "type": "array", "prefixItems": [{ "$ref": "#/$defs/viewCoordinate" }, { "$ref": "#/$defs/viewCoordinate" }], "items": false, "minItems": 2 }
+              }
+            }
+          }
+        }
+      }
+    },
+    "underlay": {
+      "description": "Sanitized SVG reference drawing on the ground (ADR-0012); at most 512 KiB of UTF-8.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["svg", "position", "width", "rotation", "opacity"],
+      "properties": {
+        "svg": { "type": "string", "maxLength": 524288 },
+        "position": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["x", "z"],
+          "properties": { "x": { "type": "number" }, "z": { "type": "number" } }
+        },
+        "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 },
+        "rotation": { "type": "number", "description": "Degrees about +Y." },
+        "opacity": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "extensions": {
+      "description": "Host or library data keyed by reverse-DNS namespace, preserved and never interpreted by core.",
+      "type": "object",
+      "propertyNames": { "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$" },
+      "additionalProperties": { "$ref": "#/$defs/json" }
+    },
+    "json": {
+      "description": "Plain JSON with strings of at most 1024 characters and no prototype keys.",
+      "anyOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string", "maxLength": 1024 },
+        { "type": "array", "items": { "$ref": "#/$defs/json" } },
+        {
+          "type": "object",
+          "propertyNames": { "not": { "enum": ["__proto__", "constructor", "prototype"] } },
+          "additionalProperties": { "$ref": "#/$defs/json" }
+        }
+      ]
+    }
+  }
+}