structured-context 0.11.0 → 0.12.0

package/dist/schema/metadata-contract.js

@@ -1,4 +1,13 @@
-export const SCHEMA_META_ID = 'https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json';
+/** The JSON Schema dialect the structured-context dialect extends. */
+export const JSON_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+export const SCHEMA_META_BASE_URL = 'https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated';
+export const SCHEMA_META_FILE = '_structured_context_schema_meta.json';
+/** Meta-schema `$id` for a dialect version folder, e.g. `.../generated/0.12.0/_structured_context_schema_meta.json`. */
+export function schemaMetaId(folder) {
+    return `${SCHEMA_META_BASE_URL}/${folder}/${SCHEMA_META_FILE}`;
+}
+/** The URL schemas set as `$schema` to follow the newest dialect. Resolves to the newest versioned meta-schema. */
+export const SCHEMA_META_ID = schemaMetaId('latest');
 /** Graph edge routing fields shared by hierarchy levels and relationships. */
 const EDGE_PROPS = {
     field: { type: 'string', minLength: 1 },
@@ -39,6 +48,7 @@ const RULE_SCHEMA = {
     properties: {
         id: { type: 'string', minLength: 1 },
         category: { enum: ['validation', 'coherence', 'workflow', 'best-practice'] },
+        severity: { enum: ['error', 'warning', 'info'] },
         description: { type: 'string', minLength: 1 },
         check: { type: 'string', minLength: 1 },
         type: { type: 'string', minLength: 1 },
@@ -48,7 +58,7 @@ const RULE_SCHEMA = {
     required: ['id', 'category', 'description', 'check'],
     additionalProperties: false,
 };
-const RULE_REF_SCHEMA = {
+const REF_SCHEMA = {
     type: 'object',
     properties: {
         $ref: { type: 'string', minLength: 1 },
@@ -56,6 +66,23 @@ const RULE_REF_SCHEMA = {
     required: ['$ref'],
     additionalProperties: false,
 };
+const HIERARCHY_SCHEMA = {
+    type: 'object',
+    properties: {
+        name: { type: 'string', minLength: 1 },
+        override: { type: 'boolean' },
+        levels: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                oneOf: [{ type: 'string', minLength: 1 }, HIERARCHY_LEVEL_SCHEMA],
+            },
+        },
+        allowSkipLevels: { type: 'boolean' },
+    },
+    required: ['levels'],
+    additionalProperties: false,
+};
 const RELATIONSHIP_SCHEMA = {
     type: 'object',
     properties: {
@@ -63,53 +90,64 @@ const RELATIONSHIP_SCHEMA = {
         type: { type: 'string', minLength: 1 },
         ...EDGE_PROPS,
         ...EMBEDDING_PROPS,
+        override: { type: 'boolean' },
     },
     required: ['parent', 'type'],
     additionalProperties: false,
 };
-export const METADATA_SCHEMA = {
-    type: 'object',
-    properties: {
-        hierarchy: {
+/** An alias target: a type name, or `{ type, override: true }` to replace an imported alias. */
+const ALIAS_SCHEMA = {
+    oneOf: [
+        { type: 'string', minLength: 1 },
+        {
             type: 'object',
             properties: {
-                levels: {
-                    type: 'array',
-                    minItems: 1,
-                    items: {
-                        oneOf: [{ type: 'string', minLength: 1 }, HIERARCHY_LEVEL_SCHEMA],
-                    },
-                },
-                allowSkipLevels: { type: 'boolean' },
+                type: { type: 'string', minLength: 1 },
+                override: { type: 'boolean' },
             },
-            required: ['levels'],
+            required: ['type'],
             additionalProperties: false,
         },
+    ],
+};
+export const METADATA_SCHEMA = {
+    type: 'object',
+    properties: {
+        // $ids of schemas whose metadata (and their imports' metadata) is merged into this schema's.
+        imports: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+        },
+        // Either declares this schema's hierarchy, or (root schema only) selects an imported one via $ref.
+        hierarchy: {
+            oneOf: [HIERARCHY_SCHEMA, REF_SCHEMA],
+        },
         relationships: {
             type: 'array',
             items: RELATIONSHIP_SCHEMA,
         },
         aliases: {
             type: 'object',
-            additionalProperties: { type: 'string', minLength: 1 },
+            additionalProperties: ALIAS_SCHEMA,
         },
         rules: {
             type: 'array',
-            items: {
-                oneOf: [RULE_SCHEMA, RULE_REF_SCHEMA],
-            },
+            items: RULE_SCHEMA,
         },
     },
     additionalProperties: false,
 };
-export const DIALECT_META_SCHEMA = {
-    $schema: 'http://json-schema.org/draft-07/schema#',
-    $id: SCHEMA_META_ID,
-    title: 'structured-context schema dialect',
-    description: 'Extends JSON Schema Draft-07 with top-level $metadata for hierarchy and rule metadata.',
-    type: 'object',
-    allOf: [{ $ref: 'http://json-schema.org/draft-07/schema#' }],
-    properties: {
-        $metadata: METADATA_SCHEMA,
-    },
-};
+/** The dialect meta-schema, published under `$id`. */
+export function buildDialectMetaSchema(id) {
+    return {
+        $schema: JSON_SCHEMA_DIALECT,
+        $id: id,
+        title: 'structured-context schema dialect',
+        description: 'Extends JSON Schema 2020-12 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.',
+        type: 'object',
+        allOf: [{ $ref: JSON_SCHEMA_DIALECT }],
+        properties: {
+            $metadata: METADATA_SCHEMA,
+        },
+    };
+}

package/dist/schema/schema.d.ts

@@ -1,17 +1,23 @@
-import { type AnySchemaObject, type ValidateFunction } from 'ajv';
+import type { AnySchemaObject, ValidateFunction } from 'ajv';
 import type { SchemaMetadata, SchemaWithMetadata } from '../types';
 export declare let bundledSchemasDir: string;
 /** Override the bundled schemas directory (e.g. when running in a bundled context). */
 export declare function setBundledSchemasDir(dir: string): void;
 export declare function readRawSchema(schemaPath: string): AnySchemaObject;
+export declare const CORE_SCHEMA_PREFIX = "sctx://core/";
+export type PluginSchemaSource = {
+    pluginName: string;
+    schemasDir: string;
+};
 /**
- * Build the full two-layer registry for a schema path:
+ * Build the full multi-layer registry for a schema path:
  * - Layer 1: bundled schemas/ dir (partials only, as fallback)
- * - Layer 2: schema's own dir (partials + target file) — overrides layer 1
- * Does not throw on $id collision; layer 2 silently wins.
+ * - Layer 2: plugin schema dirs (partials + target file if schemaPath is in this plugin's schemasDir)
+ * - Layer 3: schema's own dir (partials + target file)
+ * Throws if a lower-precedence schema collides with a reserved $id or violates namespace rules.
  */
-export declare function buildFullRegistry(schemaPath: string): Map<string, AnySchemaObject>;
-export declare function createValidator(schemaPath: string): ValidateFunction;
+export declare function buildFullRegistry(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): Map<string, AnySchemaObject>;
+export declare function createValidator(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): ValidateFunction;
 export declare function resolveNodeType(type: string, typeAliases: Record<string, string> | undefined): string;
 export interface EntityInfo {
     type: string;
@@ -20,10 +26,10 @@ export interface EntityInfo {
 }
 export declare function extractEntityInfo(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): EntityInfo[];
 export declare function extractSchemaTypeNames(schema: SchemaWithMetadata, schemaRefRegistry: Map<string, AnySchemaObject>): Set<string>;
-export declare function loadMetadata(schemaPath: string): SchemaMetadata;
+export declare function loadMetadata(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): SchemaMetadata;
 export interface LoadedSchema {
     schema: SchemaWithMetadata;
     schemaRefRegistry: Map<string, AnySchemaObject>;
     schemaValidator: ValidateFunction;
 }
-export declare function loadSchema(schemaPath: string): LoadedSchema;
+export declare function loadSchema(schemaPath: string, pluginSchemas?: PluginSchemaSource[]): LoadedSchema;