@unispechq/unispec-core 0.2.11 → 0.2.13

package/dist/cjs/converters/index.js

@@ -4,16 +4,16 @@ exports.toOpenAPI = toOpenAPI;
 exports.toGraphQLSDL = toGraphQLSDL;
 exports.toWebSocketModel = toWebSocketModel;
 function toOpenAPI(doc) {
-    const rest = (doc.protocols?.rest ?? {});
+    const rest = (doc.service?.protocols?.rest ?? {});
     const info = {
-        title: doc.name,
-        description: doc.description,
+        title: doc.service.name,
+        description: doc.service.description,
     };
     const servers = [];
     const paths = {};
     const components = {};
-    // Map doc.schemas into OpenAPI components.schemas
-    const schemas = (doc.schemas ?? {});
+    // Map doc.service.schemas into OpenAPI components.schemas
+    const schemas = (doc.service?.schemas ?? {});
     const componentsSchemas = {};
     for (const [name, def] of Object.entries(schemas)) {
         componentsSchemas[name] = def.jsonSchema;
@@ -138,13 +138,16 @@ function toGraphQLSDL(doc) {
     // via a Query field. This does not attempt to interpret the full GraphQL
     // protocol structure yet, but provides a stable, deterministic SDL shape
     // based on top-level UniSpec document fields.
-    const graphql = doc.protocols?.graphql;
+    const graphql = doc.service?.protocols?.graphql;
     const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
-        return { sdl: customSDL };
+        return {
+            sdl: customSDL,
+            url: graphql?.url
+        };
     }
-    const title = doc.name;
-    const description = doc.description ?? "";
+    const title = doc.service.name;
+    const description = doc.service.description ?? "";
     const lines = [];
     if (title || description) {
         lines.push("\"\"");
@@ -165,14 +168,17 @@ function toGraphQLSDL(doc) {
     lines.push("  _serviceInfo: String!\n");
     lines.push("}");
     const sdl = lines.join("\n");
-    return { sdl };
+    return {
+        sdl,
+        url: graphql?.url
+    };
 }
 function toWebSocketModel(doc) {
     // Base WebSocket model intended for a modern, dashboard-oriented UI.
     // It exposes service metadata, a normalized list of channels and the raw
     // websocket protocol object, while also embedding the original UniSpec
     // document under a technical key for debugging and introspection.
-    const websocket = (doc.protocols?.websocket ?? {});
+    const websocket = (doc.service?.protocols?.websocket ?? {});
     const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
     const channels = [...channelsArray]
         .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
@@ -186,10 +192,11 @@ function toWebSocketModel(doc) {
     }));
     return {
         service: {
-            name: doc.name,
+            name: doc.service.name,
             title: undefined,
-            description: doc.description,
+            description: doc.service.description,
         },
+        url: websocket.url,
         channels,
         rawProtocol: websocket,
         "x-unispec-ws": doc,

package/dist/cjs/normalizer/index.js

@@ -19,10 +19,10 @@ function normalizeValue(value) {
     return value;
 }
 function normalizeRestRoutes(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const rest = protocols.rest;
     if (!rest || !Array.isArray(rest.routes)) {
         return doc;
@@ -37,10 +37,10 @@ function normalizeRestRoutes(doc) {
     return doc;
 }
 function normalizeWebSocket(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const websocket = protocols.websocket;
     if (!websocket || !Array.isArray(websocket.channels)) {
         return doc;
@@ -68,10 +68,10 @@ function normalizeWebSocket(doc) {
     return doc;
 }
 function normalizeGraphqlOperations(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const graphql = protocols.graphql;
     if (!graphql) {
         return doc;

package/dist/cjs/schemas/index.js

@@ -32,21 +32,24 @@ function resolveSchemaRef(doc, ref) {
     const name = normalizeSchemaRef(ref);
     if (!name)
         return undefined;
-    return doc.schemas?.[name];
+    return doc.service?.schemas?.[name];
 }
 function registerSchema(doc, name, jsonSchema) {
-    if (!doc.schemas) {
-        doc.schemas = {};
+    if (!doc.service) {
+        doc.service = { name: "" };
+    }
+    if (!doc.service.schemas) {
+        doc.service.schemas = {};
     }
     const definition = {
         jsonSchema,
     };
-    doc.schemas[name] = definition;
+    doc.service.schemas[name] = definition;
     return definition;
 }
 function updateSchemaRefs(doc, mapping) {
-    const rest = doc.protocols?.rest;
-    const websocket = doc.protocols?.websocket;
+    const rest = doc.service?.protocols?.rest;
+    const websocket = doc.service?.protocols?.websocket;
     if (rest?.routes) {
         for (const route of rest.routes) {
             for (const params of [route.pathParams, route.queryParams, route.headers]) {
@@ -106,13 +109,13 @@ function updateSchemaRefs(doc, mapping) {
     }
 }
 function dedupeSchemas(doc) {
-    if (!doc.schemas)
+    if (!doc.service?.schemas)
         return;
-    const names = Object.keys(doc.schemas);
+    const names = Object.keys(doc.service.schemas);
     const hashToName = new Map();
     const renameMap = {};
     for (const name of names) {
-        const schema = doc.schemas[name];
+        const schema = doc.service.schemas[name];
         const hash = stableStringify(schema?.jsonSchema ?? null);
         const existing = hashToName.get(hash);
         if (!existing) {
@@ -126,6 +129,6 @@ function dedupeSchemas(doc) {
         return;
     updateSchemaRefs(doc, renameMap);
     for (const dup of duplicates) {
-        delete doc.schemas[dup];
+        delete doc.service.schemas[dup];
     }
 }

package/dist/cjs/validator/generated-schemas.js

@@ -396,7 +396,7 @@ exports.GENERATED_SCHEMAS = {
                 "Identifier": {
                     "type": "string",
                     "description": "Identifier for services, operations, channels, etc.",
-                    "pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
+                    "pattern": "^[A-Za-z_][A-Za-z0-9_.:-]*$"
                 },
                 "Description": {
                     "type": "string",
@@ -436,6 +436,10 @@ exports.GENERATED_SCHEMAS = {
                 }
             },
             "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "Optional path or URL of the GraphQL endpoint. Recommended: relative path (e.g. '/graphql'). Absolute URLs are allowed only if the service is tightly bound to a single host. If omitted, tooling may assume a framework default (commonly '/graphql')."
+                },
                 "schema": {
                     "type": "string",
                     "description": "GraphQL schema SDL as a string. Canonical source of type definitions."
@@ -788,6 +792,10 @@ exports.GENERATED_SCHEMAS = {
                 }
             },
             "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "Optional path or URL of the WebSocket endpoint. Recommended: relative path (e.g. '/ws' or '/socket.io' for Socket.IO). Absolute URLs are allowed only if the service is tightly bound to a single host. If omitted, tooling may assume a framework default (commonly '/ws' for WebSocket servers or '/socket.io' for Socket.IO)."
+                },
                 "channels": {
                     "type": "array",
                     "description": "WebSocket channels/topics exposed by the service.",

package/dist/cjs/validator/index.js

@@ -61,15 +61,10 @@ function mapAjvErrors(errors) {
  */
 async function validateUniSpec(doc, options = {}) {
     const { validateUniSpecFn } = await getValidator(options);
+    // Ensure the document has required fields for validation
     const docForValidation = {
-        unispecVersion: "0.0.0",
-        service: {
-            name: doc.name,
-            description: doc.description,
-            version: doc.version,
-            protocols: doc.protocols,
-            schemas: doc.schemas,
-        },
+        unispecVersion: doc.unispecVersion || "1.0.0",
+        service: doc.service,
         extensions: doc.extensions,
     };
     const valid = validateUniSpecFn(docForValidation);

package/dist/converters/index.d.ts

@@ -4,6 +4,7 @@ export interface OpenAPIDocument {
 }
 export interface GraphQLSDLOutput {
     sdl: string;
+    url?: string;
 }
 export interface WebSocketModel {
     [key: string]: unknown;

package/dist/converters/index.js

@@ -1,14 +1,14 @@
 export function toOpenAPI(doc) {
-    const rest = (doc.protocols?.rest ?? {});
+    const rest = (doc.service?.protocols?.rest ?? {});
     const info = {
-        title: doc.name,
-        description: doc.description,
+        title: doc.service.name,
+        description: doc.service.description,
     };
     const servers = [];
     const paths = {};
     const components = {};
-    // Map doc.schemas into OpenAPI components.schemas
-    const schemas = (doc.schemas ?? {});
+    // Map doc.service.schemas into OpenAPI components.schemas
+    const schemas = (doc.service?.schemas ?? {});
     const componentsSchemas = {};
     for (const [name, def] of Object.entries(schemas)) {
         componentsSchemas[name] = def.jsonSchema;
@@ -133,13 +133,16 @@ export function toGraphQLSDL(doc) {
     // via a Query field. This does not attempt to interpret the full GraphQL
     // protocol structure yet, but provides a stable, deterministic SDL shape
     // based on top-level UniSpec document fields.
-    const graphql = doc.protocols?.graphql;
+    const graphql = doc.service?.protocols?.graphql;
     const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
-        return { sdl: customSDL };
+        return {
+            sdl: customSDL,
+            url: graphql?.url
+        };
     }
-    const title = doc.name;
-    const description = doc.description ?? "";
+    const title = doc.service.name;
+    const description = doc.service.description ?? "";
     const lines = [];
     if (title || description) {
         lines.push("\"\"");
@@ -160,14 +163,17 @@ export function toGraphQLSDL(doc) {
     lines.push("  _serviceInfo: String!\n");
     lines.push("}");
     const sdl = lines.join("\n");
-    return { sdl };
+    return {
+        sdl,
+        url: graphql?.url
+    };
 }
 export function toWebSocketModel(doc) {
     // Base WebSocket model intended for a modern, dashboard-oriented UI.
     // It exposes service metadata, a normalized list of channels and the raw
     // websocket protocol object, while also embedding the original UniSpec
     // document under a technical key for debugging and introspection.
-    const websocket = (doc.protocols?.websocket ?? {});
+    const websocket = (doc.service?.protocols?.websocket ?? {});
     const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
     const channels = [...channelsArray]
         .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
@@ -181,10 +187,11 @@ export function toWebSocketModel(doc) {
     }));
     return {
         service: {
-            name: doc.name,
+            name: doc.service.name,
             title: undefined,
-            description: doc.description,
+            description: doc.service.description,
         },
+        url: websocket.url,
         channels,
         rawProtocol: websocket,
         "x-unispec-ws": doc,

package/dist/normalizer/index.js

@@ -16,10 +16,10 @@ function normalizeValue(value) {
     return value;
 }
 function normalizeRestRoutes(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const rest = protocols.rest;
     if (!rest || !Array.isArray(rest.routes)) {
         return doc;
@@ -34,10 +34,10 @@ function normalizeRestRoutes(doc) {
     return doc;
 }
 function normalizeWebSocket(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const websocket = protocols.websocket;
     if (!websocket || !Array.isArray(websocket.channels)) {
         return doc;
@@ -65,10 +65,10 @@ function normalizeWebSocket(doc) {
     return doc;
 }
 function normalizeGraphqlOperations(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const graphql = protocols.graphql;
     if (!graphql) {
         return doc;

package/dist/schemas/index.js

@@ -27,21 +27,24 @@ export function resolveSchemaRef(doc, ref) {
     const name = normalizeSchemaRef(ref);
     if (!name)
         return undefined;
-    return doc.schemas?.[name];
+    return doc.service?.schemas?.[name];
 }
 export function registerSchema(doc, name, jsonSchema) {
-    if (!doc.schemas) {
-        doc.schemas = {};
+    if (!doc.service) {
+        doc.service = { name: "" };
+    }
+    if (!doc.service.schemas) {
+        doc.service.schemas = {};
     }
     const definition = {
         jsonSchema,
     };
-    doc.schemas[name] = definition;
+    doc.service.schemas[name] = definition;
     return definition;
 }
 function updateSchemaRefs(doc, mapping) {
-    const rest = doc.protocols?.rest;
-    const websocket = doc.protocols?.websocket;
+    const rest = doc.service?.protocols?.rest;
+    const websocket = doc.service?.protocols?.websocket;
     if (rest?.routes) {
         for (const route of rest.routes) {
             for (const params of [route.pathParams, route.queryParams, route.headers]) {
@@ -101,13 +104,13 @@ function updateSchemaRefs(doc, mapping) {
     }
 }
 export function dedupeSchemas(doc) {
-    if (!doc.schemas)
+    if (!doc.service?.schemas)
         return;
-    const names = Object.keys(doc.schemas);
+    const names = Object.keys(doc.service.schemas);
     const hashToName = new Map();
     const renameMap = {};
     for (const name of names) {
-        const schema = doc.schemas[name];
+        const schema = doc.service.schemas[name];
         const hash = stableStringify(schema?.jsonSchema ?? null);
         const existing = hashToName.get(hash);
         if (!existing) {
@@ -121,6 +124,6 @@ export function dedupeSchemas(doc) {
         return;
     updateSchemaRefs(doc, renameMap);
     for (const dup of duplicates) {
-        delete doc.schemas[dup];
+        delete doc.service.schemas[dup];
     }
 }

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export interface UniSpecGraphQLOperation {
     deprecationReason?: string;
 }
 export interface UniSpecGraphQLProtocol {
+    url?: string;
     schema?: string;
     queries?: UniSpecGraphQLOperation[];
     mutations?: UniSpecGraphQLOperation[];
@@ -26,6 +27,7 @@ export interface UniSpecWebSocketChannel {
     extensions?: Record<string, unknown>;
 }
 export interface UniSpecWebSocketProtocol {
+    url?: string;
     channels?: UniSpecWebSocketChannel[];
     securitySchemes?: Record<string, Record<string, unknown>>;
 }
@@ -86,12 +88,16 @@ export interface UniSpecServiceProtocols {
     websocket?: UniSpecWebSocketProtocol;
 }
 export interface UniSpecDocument {
+    unispecVersion: string;
+    service: UniSpecService;
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecService {
     name: string;
     description?: string;
     version?: string;
     protocols?: UniSpecServiceProtocols;
     schemas?: UniSpecSchemas;
-    extensions?: Record<string, unknown>;
 }
 export interface ValidationError {
     message: string;

package/dist/validator/generated-schemas.d.ts

@@ -411,6 +411,10 @@ export declare const GENERATED_SCHEMAS: {
             Channel?: undefined;
         };
         properties: {
+            url: {
+                type: string;
+                description: string;
+            };
             schema: {
                 type: string;
                 description: string;
@@ -618,6 +622,7 @@ export declare const GENERATED_SCHEMAS: {
                     additionalProperties: boolean;
                 };
             };
+            url?: undefined;
             schema?: undefined;
             queries?: undefined;
             mutations?: undefined;
@@ -706,6 +711,7 @@ export declare const GENERATED_SCHEMAS: {
             schemas: {
                 $ref: string;
             };
+            url?: undefined;
             schema?: undefined;
             queries?: undefined;
             mutations?: undefined;
@@ -797,6 +803,10 @@ export declare const GENERATED_SCHEMAS: {
             SchemaDefinition?: undefined;
         };
         properties: {
+            url: {
+                type: string;
+                description: string;
+            };
             channels: {
                 type: string;
                 description: string;

package/dist/validator/generated-schemas.js

@@ -393,7 +393,7 @@ export const GENERATED_SCHEMAS = {
                 "Identifier": {
                     "type": "string",
                     "description": "Identifier for services, operations, channels, etc.",
-                    "pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
+                    "pattern": "^[A-Za-z_][A-Za-z0-9_.:-]*$"
                 },
                 "Description": {
                     "type": "string",
@@ -433,6 +433,10 @@ export const GENERATED_SCHEMAS = {
                 }
             },
             "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "Optional path or URL of the GraphQL endpoint. Recommended: relative path (e.g. '/graphql'). Absolute URLs are allowed only if the service is tightly bound to a single host. If omitted, tooling may assume a framework default (commonly '/graphql')."
+                },
                 "schema": {
                     "type": "string",
                     "description": "GraphQL schema SDL as a string. Canonical source of type definitions."
@@ -785,6 +789,10 @@ export const GENERATED_SCHEMAS = {
                 }
             },
             "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "Optional path or URL of the WebSocket endpoint. Recommended: relative path (e.g. '/ws' or '/socket.io' for Socket.IO). Absolute URLs are allowed only if the service is tightly bound to a single host. If omitted, tooling may assume a framework default (commonly '/ws' for WebSocket servers or '/socket.io' for Socket.IO)."
+                },
                 "channels": {
                     "type": "array",
                     "description": "WebSocket channels/topics exposed by the service.",

package/dist/validator/index.js

@@ -54,15 +54,10 @@ function mapAjvErrors(errors) {
  */
 export async function validateUniSpec(doc, options = {}) {
     const { validateUniSpecFn } = await getValidator(options);
+    // Ensure the document has required fields for validation
     const docForValidation = {
-        unispecVersion: "0.0.0",
-        service: {
-            name: doc.name,
-            description: doc.description,
-            version: doc.version,
-            protocols: doc.protocols,
-            schemas: doc.schemas,
-        },
+        unispecVersion: doc.unispecVersion || "1.0.0",
+        service: doc.service,
         extensions: doc.extensions,
     };
     const valid = validateUniSpecFn(docForValidation);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unispechq/unispec-core",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Central UniSpec Core Engine providing parsing, validation, normalization, diffing, and conversion of UniSpec specs.",
   "license": "MIT",
   "repository": {
@@ -49,7 +49,7 @@
     "release:major": "node scripts/release.js major"
   },
   "dependencies": {
-    "@unispechq/unispec-schema": "^0.3.4",
+    "@unispechq/unispec-schema": "^0.3.6",
     "ajv": "^8.12.0"
   },
   "optionalDependencies": {