@vev-software/atlas-contracts 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,38 @@
+# @vev-software/atlas-contracts
+
+Public, versioned **data model and interop contracts** for VEV Atlas — the portability and
+interoperability surface that the Atlas runtime and third-party importers/exporters all build
+against, without reaching into anyone's internals.
+
+```sh
+npm i @vev-software/atlas-contracts
+```
+
+```ts
+import type { LandscapeDocument, Asset } from "@vev-software/atlas-contracts";
+```
+
+## What's inside
+
+- **Asset data model** — the catalogue of systems, applications, servers and infrastructure,
+  plus the manual **relationships** and **tags** that connect and classify them.
+- **Landscape import/export document** — the schema that carries a whole landscape across a
+  boundary (customer-owned export; community importers/exporters).
+- **Authoritative JSON Schemas** — shipped under `schemas/` in the package, so you can validate
+  payloads against the exact same contracts the TypeScript types describe.
+
+Ships type declarations (`dist/index.d.ts`) and ESM; no runtime dependencies.
+
+## Versioning
+
+[SemVer](https://semver.org), derived from the git tag (`vX.Y.Z`) at release. Pre-1.0, the v1
+contract evolves additively across minor/patch versions.
+
+## Links
+
+- **Source & issues:** https://github.com/Vev-software/atlas-contracts
+- **.NET SDK (NuGet):** [`Vev.Atlas.Contracts`](https://www.nuget.org/packages/Vev.Atlas.Contracts)
+
+## Licence
+
+[Apache-2.0](https://github.com/Vev-software/atlas-contracts/blob/main/LICENSE).

package/dist/index.d.ts

@@ -56,6 +56,7 @@ export interface ColumnDetails {
 /** A single catalogued asset. */
 export interface Asset {
     id: string;
+    numericId?: number;
     kind: AssetKind;
     name: string;
     lifecycle: Lifecycle;

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@vev-software/atlas-contracts",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Public, versioned data model and interop contracts for VEV Atlas — the catalogue asset model plus manual relationships, tags and the landscape import/export document.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "schemas"],
+  "files": [
+    "dist",
+    "schemas"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/Vev-software/atlas-contracts"

package/schemas/v1/asset.schema.json

@@ -8,6 +8,11 @@
   "required": ["id", "kind", "name", "lifecycle"],
   "properties": {
     "id": { "$ref": "common.schema.json#/$defs/AssetId" },
+    "numericId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Stable numeric identifier assigned by Atlas when the asset is created. Immutable, and independent of the editable name and human-readable id."
+    },
     "kind": { "$ref": "common.schema.json#/$defs/AssetKind" },
     "name": {
       "type": "string",
@@ -73,6 +78,22 @@
           "column": { "$ref": "common.schema.json#/$defs/ColumnDetails" }
         }
       }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "ai-service" } } },
+      "then": {
+        "properties": {
+          "aiService": { "$ref": "common.schema.json#/$defs/AiServiceDetails" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "ai-model" } } },
+      "then": {
+        "properties": {
+          "aiModel": { "$ref": "common.schema.json#/$defs/AiModelDetails" }
+        }
+      }
     }
   ]
 }

package/schemas/v1/common.schema.json

@@ -6,8 +6,8 @@
   "$defs": {
     "AssetKind": {
       "type": "string",
-      "description": "The kind of asset held in the catalogue. The data-layer kinds (data-area, dataset, column) model the data architecture beneath a system, down to the column.",
-      "enum": ["system", "application", "server", "infrastructure", "data-area", "dataset", "column"]
+      "description": "The kind of asset held in the catalogue. The data-layer kinds (data-area, dataset, column) model the data architecture beneath a system, down to the column. The AI kinds (ai-service, ai-model) catalogue AI platforms and models as first-class assets.",
+      "enum": ["system", "application", "server", "infrastructure", "data-area", "dataset", "column", "ai-service", "ai-model"]
     },
     "Lifecycle": {
       "type": "string",
@@ -124,6 +124,27 @@
         "dataType": { "type": ["string", "null"], "maxLength": 128 },
         "nullable": { "type": ["boolean", "null"] }
       }
+    },
+    "AiServiceDetails": {
+      "type": "object",
+      "description": "Held AI service metadata. Cataloguing only: provider, endpoint and environment are recorded facts, never analysis.",
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "type": ["string", "null"], "maxLength": 128 },
+        "endpoint": { "type": ["string", "null"], "maxLength": 512 },
+        "environment": { "type": ["string", "null"], "maxLength": 64 }
+      }
+    },
+    "AiModelDetails": {
+      "type": "object",
+      "description": "Held AI model metadata. Cataloguing only: model name, version, provider and embedding dimensions are recorded facts, never analysis.",
+      "additionalProperties": false,
+      "properties": {
+        "modelName": { "type": ["string", "null"], "maxLength": 128 },
+        "version": { "type": ["string", "null"], "maxLength": 64 },
+        "provider": { "type": ["string", "null"], "maxLength": 128 },
+        "embeddingDimensions": { "type": ["integer", "null"] }
+      }
     }
   }
 }

package/schemas/v1/import.schema.json

@@ -80,6 +80,14 @@
         {
           "if": { "properties": { "kind": { "const": "column" } } },
           "then": { "properties": { "column": { "$ref": "common.schema.json#/$defs/ColumnDetails" } } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "ai-service" } } },
+          "then": { "properties": { "aiService": { "$ref": "common.schema.json#/$defs/AiServiceDetails" } } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "ai-model" } } },
+          "then": { "properties": { "aiModel": { "$ref": "common.schema.json#/$defs/AiModelDetails" } } }
         }
       ]
     },