@unispechq/unispec-core 0.1.2 → 0.2.0

package/README.md

@@ -59,7 +59,7 @@ Core Engine provides:
 
 - YAML/JSON loader  
 - JSON Schema validator  
-– Normalizer → canonical UniSpec output (REST paths/methods, GraphQL operations, WebSocket channels/messages)  
+– Normalizer → canonical UniSpec output (REST routes, GraphQL operations, WebSocket channels/messages)  
 – Diff engine (with basic breaking / non-breaking classification for REST, GraphQL and WebSocket)  
 – Converters:  
   - UniSpec → OpenAPI (REST-centric)  
@@ -77,19 +77,19 @@ This is the foundation used by:
 At the level of the Core Engine, protocol support is intentionally minimal but deterministic:
 
 - **REST**  
-  - Treated as a general OpenAPI-like structure defined by UniSpec JSON Schemas.  
-  - Normalizer orders `paths` and HTTP methods for stable diffs.  
-  - Diff engine annotates path/operation additions and removals with breaking/non-breaking severity.  
-  - Converter exposes REST as an OpenAPI 3.1 document while preserving the original UniSpec under `x-unispec`.
+  - Typed REST surface defined by `service.protocols.rest.routes[]` and reusable `service.schemas`.  
+  - Normalizer orders routes by `name` (or `path + method`) for stable diffs.  
+  - Diff engine annotates route additions and removals with breaking/non-breaking severity.  
+  - Converter exposes REST as an OpenAPI 3.1 document built from routes, schemas and environments, while preserving the original UniSpec under `x-unispec`.
 
 - **GraphQL**  
-  - Typed protocol with `schema` (SDL) and `operations` (queries/mutations/subscriptions).  
+  - Typed protocol with `schema` (SDL string) and `queries`/`mutations`/`subscriptions` as operation lists.  
   - Normalizer orders operation names within each bucket.  
   - Diff engine annotates operation additions/removals as non-breaking/breaking.  
   - Converter either passes through user-provided SDL or generates a minimal, deterministic SDL shell.
 
 - **WebSocket**  
-  - Typed protocol with channels and messages, plus extensions.  
+  - Typed protocol with channels and messages backed by reusable schemas and security schemes.  
   - Normalizer orders channels by name and messages by `name` within each channel.  
   - Diff engine annotates channel/message additions/removals as non-breaking/breaking changes.  
   - Converter produces a dashboard-friendly model with service metadata, a normalized channel list and the raw protocol.

package/dist/converters/index.js

@@ -1,22 +1,137 @@
 export function toOpenAPI(doc) {
     const service = doc.service;
-    const rest = service.protocols?.rest;
+    const rest = (service.protocols?.rest ?? {});
     const info = {
         title: service.title ?? service.name,
         description: service.description,
     };
-    const servers = rest?.servers ?? [];
-    const paths = rest?.paths ?? {};
-    // Transparently forward additional REST protocol fields into the OpenAPI document.
-    // This allows users to describe components, security, tags and other structures
-    // without forcing a specific REST model at the core layer.
-    const { servers: _omitServers, paths: _omitPaths, ...restExtras } = rest ?? {};
+    // Derive OpenAPI servers from UniSpec environments when available.
+    const servers = Array.isArray(service.environments)
+        ? service.environments.map((env) => ({
+            url: env.baseUrl,
+            description: env.name,
+        }))
+        : [];
+    const paths = {};
+    const components = {};
+    // Map service.schemas into OpenAPI components.schemas
+    const schemas = (service.schemas ?? {});
+    const componentsSchemas = {};
+    for (const [name, def] of Object.entries(schemas)) {
+        componentsSchemas[name] = def.jsonSchema;
+    }
+    if (Object.keys(componentsSchemas).length > 0) {
+        components.schemas = componentsSchemas;
+    }
+    // Helper to build a $ref into components.schemas when schemaRef is present.
+    function schemaRefToOpenAPI(schemaRef) {
+        if (!schemaRef) {
+            return {};
+        }
+        return { $ref: `#/components/schemas/${schemaRef}` };
+    }
+    // Build paths from REST routes.
+    if (Array.isArray(rest.routes)) {
+        for (const route of rest.routes) {
+            const pathItem = (paths[route.path] ?? {});
+            const method = route.method.toLowerCase();
+            const parameters = [];
+            // Path params
+            for (const param of route.pathParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "path",
+                    required: param.required ?? true,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Query params
+            for (const param of route.queryParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "query",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Header params
+            for (const param of route.headers ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "header",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Request body
+            let requestBody;
+            if (route.requestBody && route.requestBody.content) {
+                const content = {};
+                for (const [mediaType, media] of Object.entries(route.requestBody.content)) {
+                    content[mediaType] = {
+                        schema: schemaRefToOpenAPI(media.schemaRef),
+                    };
+                }
+                requestBody = {
+                    description: route.requestBody.description,
+                    required: route.requestBody.required,
+                    content,
+                };
+            }
+            // Responses
+            const responses = {};
+            for (const [status, resp] of Object.entries(route.responses ?? {})) {
+                const content = {};
+                if (resp.content) {
+                    for (const [mediaType, media] of Object.entries(resp.content)) {
+                        content[mediaType] = {
+                            schema: schemaRefToOpenAPI(media.schemaRef),
+                        };
+                    }
+                }
+                responses[status] = {
+                    description: resp.description ?? "",
+                    ...(Object.keys(content).length > 0 ? { content } : {}),
+                };
+            }
+            const operation = {
+                operationId: route.name,
+                summary: route.summary,
+                description: route.description,
+                ...(parameters.length > 0 ? { parameters } : {}),
+                responses: Object.keys(responses).length > 0 ? responses : { default: { description: "" } },
+            };
+            if (requestBody) {
+                operation.requestBody = requestBody;
+            }
+            // Security requirements
+            if (Array.isArray(route.security) && route.security.length > 0) {
+                operation.security = route.security.map((req) => {
+                    const obj = {};
+                    for (const schemeName of req) {
+                        obj[schemeName] = [];
+                    }
+                    return obj;
+                });
+            }
+            pathItem[method] = operation;
+            paths[route.path] = pathItem;
+        }
+    }
+    // Security schemes pass-through from REST protocol
+    const componentsSecuritySchemes = rest.securitySchemes ?? {};
+    if (Object.keys(componentsSecuritySchemes).length > 0) {
+        components.securitySchemes = componentsSecuritySchemes;
+    }
     return {
         openapi: "3.1.0",
         info,
         servers,
         paths,
-        ...restExtras,
+        ...(Object.keys(components).length > 0 ? { components } : {}),
         "x-unispec": doc,
     };
 }
@@ -26,7 +141,7 @@ export function toGraphQLSDL(doc) {
     // protocol structure yet, but provides a stable, deterministic SDL shape
     // based on top-level UniSpec document fields.
     const graphql = doc.service.protocols?.graphql;
-    const customSDL = graphql?.schema?.sdl;
+    const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
         return { sdl: customSDL };
     }
@@ -62,20 +177,17 @@ export function toWebSocketModel(doc) {
     // document under a technical key for debugging and introspection.
     const service = doc.service;
     const websocket = (service.protocols?.websocket ?? {});
-    const channelsRecord = (websocket && typeof websocket === "object" && websocket.channels && typeof websocket.channels === "object")
-        ? websocket.channels
-        : {};
-    const channels = Object.keys(channelsRecord).sort().map((name) => {
-        const channel = channelsRecord[name] ?? {};
-        return {
-            name,
-            summary: channel.summary ?? channel.title,
-            description: channel.description,
-            direction: channel.direction,
-            messages: channel.messages,
-            raw: channel,
-        };
-    });
+    const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
+    const channels = [...channelsArray]
+        .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
+        .map((channel) => ({
+        name: channel.name,
+        summary: undefined,
+        description: channel.description,
+        direction: channel.direction,
+        messages: channel.messages,
+        raw: channel,
+    }));
     return {
         service: {
             name: service.name,

package/dist/diff/index.js

@@ -34,8 +34,54 @@ function diffValues(oldVal, newVal, basePath, out) {
         }
         return;
     }
-    // Arrays → shallow compare by index for now
+    // Arrays
     if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+        // Special handling for UniSpec collections identified by "name"
+        const isNamedCollection = basePath === "/service/protocols/rest/routes" ||
+            basePath === "/service/protocols/websocket/channels" ||
+            basePath === "/service/protocols/graphql/queries" ||
+            basePath === "/service/protocols/graphql/mutations" ||
+            basePath === "/service/protocols/graphql/subscriptions";
+        if (isNamedCollection) {
+            const oldByName = new Map();
+            const newByName = new Map();
+            for (const item of oldVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    oldByName.set(item.name, item);
+                }
+            }
+            for (const item of newVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    newByName.set(item.name, item);
+                }
+            }
+            // Removed
+            for (const [name, oldItem] of oldByName.entries()) {
+                if (!newByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item removed",
+                        severity: "unknown",
+                    });
+                }
+                else {
+                    const newItem = newByName.get(name);
+                    diffValues(oldItem, newItem, `${basePath}/${name}`, out);
+                }
+            }
+            // Added
+            for (const [name] of newByName.entries()) {
+                if (!oldByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item added",
+                        severity: "unknown",
+                    });
+                }
+            }
+            return;
+        }
+        // Generic shallow index-based compare
         const maxLen = Math.max(oldVal.length, newVal.length);
         for (let i = 0; i < maxLen; i++) {
             const childPath = `${basePath}/${i}`;
@@ -67,40 +113,29 @@ function diffValues(oldVal, newVal, basePath, out) {
     });
 }
 function annotateRestChange(change) {
-    if (!change.path.startsWith("/service/protocols/rest/paths/")) {
+    if (!change.path.startsWith("/service/protocols/rest/routes/")) {
         return change;
     }
     const segments = change.path.split("/").filter(Boolean);
-    // Expected shape: ["service", "protocols", "rest", "paths", pathKey?, method?]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "paths") {
+    // Expected shape: ["service", "protocols", "rest", "routes", index]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "routes") {
+        return change;
+    }
+    const index = segments[4];
+    if (typeof index === "undefined") {
         return change;
     }
-    const pathKey = segments[4];
-    const method = segments[5];
-    const httpMethods = new Set(["get", "head", "options", "post", "put", "patch", "delete"]);
     const annotated = {
         ...change,
         protocol: "rest",
     };
-    if (change.description === "Field removed") {
-        if (pathKey && !method) {
-            annotated.kind = "rest.path.removed";
-            annotated.severity = "breaking";
-        }
-        else if (pathKey && method && httpMethods.has(method)) {
-            annotated.kind = "rest.operation.removed";
-            annotated.severity = "breaking";
-        }
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
     }
-    else if (change.description === "Field added") {
-        if (pathKey && !method) {
-            annotated.kind = "rest.path.added";
-            annotated.severity = "non-breaking";
-        }
-        else if (pathKey && method && httpMethods.has(method)) {
-            annotated.kind = "rest.operation.added";
-            annotated.severity = "non-breaking";
-        }
+    else if (change.description === "Item added" || change.description === "Field added") {
+        annotated.kind = "rest.route.added";
+        annotated.severity = "non-breaking";
     }
     return annotated;
 }
@@ -109,35 +144,35 @@ function annotateWebSocketChange(change) {
         return change;
     }
     const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","websocket","channels", channelName, ...]
+    // Expected base: ["service","protocols","websocket","channels", channelIndex, ...]
     if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
         return change;
     }
-    const channelName = segments[4];
+    const channelIndex = segments[4];
     const next = segments[5];
     const annotated = {
         ...change,
         protocol: "websocket",
     };
-    if (!channelName) {
+    if (typeof channelIndex === "undefined") {
         return annotated;
     }
-    // Channel-level changes
+    // Channel-level changes: /service/protocols/websocket/channels/{index}
     if (!next) {
-        if (change.description === "Field removed") {
+        if (change.description === "Item removed" || change.description === "Field removed") {
             annotated.kind = "websocket.channel.removed";
             annotated.severity = "breaking";
         }
-        else if (change.description === "Field added") {
+        else if (change.description === "Item added" || change.description === "Field added") {
             annotated.kind = "websocket.channel.added";
             annotated.severity = "non-breaking";
         }
         return annotated;
     }
-    // Message-level changes (channels/{channelName}/messages/{index})
+    // Message-level changes: /service/protocols/websocket/channels/{index}/messages/{msgIndex}
     if (next === "messages") {
-        const index = segments[6];
-        if (typeof index === "undefined") {
+        const messageIndex = segments[6];
+        if (typeof messageIndex === "undefined") {
             return annotated;
         }
         if (change.description === "Item removed") {
@@ -152,28 +187,31 @@ function annotateWebSocketChange(change) {
     return annotated;
 }
 function annotateGraphQLChange(change) {
-    if (!change.path.startsWith("/service/protocols/graphql/operations/")) {
+    if (!change.path.startsWith("/service/protocols/graphql/")) {
         return change;
     }
     const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","graphql","operations", kind, opName?]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql" || segments[3] !== "operations") {
+    // Expected: ["service","protocols","graphql", kind, index, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql") {
+        return change;
+    }
+    const opKind = segments[3];
+    const index = segments[4];
+    if (!opKind || typeof index === "undefined") {
         return change;
     }
-    const opKind = segments[4];
-    const opName = segments[5];
-    if (!opKind || !opName) {
+    if (opKind !== "queries" && opKind !== "mutations" && opKind !== "subscriptions") {
         return change;
     }
     const annotated = {
         ...change,
         protocol: "graphql",
     };
-    if (change.description === "Field removed") {
+    if (change.description === "Item removed" || change.description === "Field removed") {
         annotated.kind = "graphql.operation.removed";
         annotated.severity = "breaking";
     }
-    else if (change.description === "Field added") {
+    else if (change.description === "Item added" || change.description === "Field added") {
         annotated.kind = "graphql.operation.added";
         annotated.severity = "non-breaking";
     }

package/dist/normalizer/index.js

@@ -15,37 +15,22 @@ function normalizeValue(value) {
     }
     return value;
 }
-function normalizeRestPaths(doc) {
+function normalizeRestRoutes(doc) {
     if (!doc || !doc.service || !doc.service.protocols) {
         return doc;
     }
     const protocols = doc.service.protocols;
     const rest = protocols.rest;
-    if (!rest || !rest.paths || typeof rest.paths !== "object") {
+    if (!rest || !Array.isArray(rest.routes)) {
         return doc;
     }
-    const httpMethodOrder = ["get", "head", "options", "post", "put", "patch", "delete"];
-    const normalizedPaths = {};
-    for (const path of Object.keys(rest.paths).sort()) {
-        const pathItem = rest.paths[path];
-        if (!pathItem || typeof pathItem !== "object") {
-            normalizedPaths[path] = pathItem;
-            continue;
-        }
-        const pathItemObj = pathItem;
-        const ordered = {};
-        for (const method of httpMethodOrder) {
-            if (Object.prototype.hasOwnProperty.call(pathItemObj, method)) {
-                ordered[method] = pathItemObj[method];
-            }
-        }
-        const remainingKeys = Object.keys(pathItemObj).filter((k) => !httpMethodOrder.includes(k)).sort();
-        for (const key of remainingKeys) {
-            ordered[key] = pathItemObj[key];
-        }
-        normalizedPaths[path] = ordered;
-    }
-    rest.paths = normalizedPaths;
+    const routes = [...rest.routes];
+    routes.sort((a, b) => {
+        const keyA = a.name || `${a.path} ${a.method}`;
+        const keyB = b.name || `${b.path} ${b.method}`;
+        return keyA.localeCompare(keyB);
+    });
+    rest.routes = routes;
     return doc;
 }
 function normalizeWebSocket(doc) {
@@ -54,30 +39,29 @@ function normalizeWebSocket(doc) {
     }
     const protocols = doc.service.protocols;
     const websocket = protocols.websocket;
-    if (!websocket || !websocket.channels || typeof websocket.channels !== "object") {
+    if (!websocket || !Array.isArray(websocket.channels)) {
         return doc;
     }
-    const originalChannels = websocket.channels;
-    const sortedChannels = {};
-    for (const name of Object.keys(originalChannels).sort()) {
-        const channel = originalChannels[name];
-        if (!channel) {
-            continue;
-        }
-        let messages = channel.messages;
-        if (Array.isArray(messages)) {
-            messages = [...messages].sort((a, b) => {
-                const aName = a?.name ?? "";
-                const bName = b?.name ?? "";
-                return aName.localeCompare(bName);
-            });
+    const channels = websocket.channels.map((channel) => {
+        if (!channel || !Array.isArray(channel.messages)) {
+            return channel;
         }
-        sortedChannels[name] = {
+        const sortedMessages = [...channel.messages].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+        return {
             ...channel,
-            ...(messages ? { messages } : {}),
+            messages: sortedMessages,
         };
-    }
-    websocket.channels = sortedChannels;
+    });
+    channels.sort((a, b) => {
+        const aName = a?.name ?? "";
+        const bName = b?.name ?? "";
+        return aName.localeCompare(bName);
+    });
+    websocket.channels = channels;
     return doc;
 }
 function normalizeGraphqlOperations(doc) {
@@ -86,20 +70,24 @@ function normalizeGraphqlOperations(doc) {
     }
     const protocols = doc.service.protocols;
     const graphql = protocols.graphql;
-    if (!graphql || !graphql.operations) {
+    if (!graphql) {
         return doc;
     }
-    const kinds = ["queries", "mutations", "subscriptions"];
+    const kinds = [
+        "queries",
+        "mutations",
+        "subscriptions",
+    ];
     for (const kind of kinds) {
-        const bucket = graphql.operations[kind];
-        if (!bucket || typeof bucket !== "object") {
+        const ops = graphql[kind];
+        if (!Array.isArray(ops)) {
             continue;
         }
-        const sorted = {};
-        for (const name of Object.keys(bucket).sort()) {
-            sorted[name] = bucket[name];
-        }
-        graphql.operations[kind] = sorted;
+        graphql[kind] = [...ops].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
     }
     return doc;
 }
@@ -112,5 +100,5 @@ function normalizeGraphqlOperations(doc) {
  */
 export function normalizeUniSpec(doc, _options = {}) {
     const normalized = normalizeValue(doc);
-    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestPaths(normalized)));
+    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestRoutes(normalized)));
 }

package/dist/types/index.d.ts

@@ -1,37 +1,87 @@
-export interface UniSpecGraphQLSchema {
-    sdl?: string;
-}
-export interface UniSpecGraphQLOperations {
-    queries?: Record<string, unknown>;
-    mutations?: Record<string, unknown>;
-    subscriptions?: Record<string, unknown>;
+export interface UniSpecGraphQLOperation {
+    name: string;
+    description?: string;
+    deprecated?: boolean;
+    deprecationReason?: string;
 }
 export interface UniSpecGraphQLProtocol {
-    schema?: UniSpecGraphQLSchema;
-    operations?: UniSpecGraphQLOperations;
-    extensions?: Record<string, unknown>;
+    schema?: string;
+    queries?: UniSpecGraphQLOperation[];
+    mutations?: UniSpecGraphQLOperation[];
+    subscriptions?: UniSpecGraphQLOperation[];
+}
+export interface UniSpecSecurityRequirement extends Array<string> {
 }
 export interface UniSpecWebSocketMessage {
-    name?: string;
-    summary?: string;
+    name: string;
     description?: string;
-    payload?: unknown;
-    extensions?: Record<string, unknown>;
+    schemaRef?: string;
 }
 export interface UniSpecWebSocketChannel {
-    summary?: string;
-    title?: string;
+    name: string;
     description?: string;
-    direction?: string;
+    direction?: "publish" | "subscribe" | "both";
     messages?: UniSpecWebSocketMessage[];
+    security?: UniSpecSecurityRequirement[];
     extensions?: Record<string, unknown>;
 }
 export interface UniSpecWebSocketProtocol {
-    channels?: Record<string, UniSpecWebSocketChannel>;
-    extensions?: Record<string, unknown>;
+    channels?: UniSpecWebSocketChannel[];
+    securitySchemes?: Record<string, Record<string, unknown>>;
+}
+export interface UniSpecRestParameter {
+    name: string;
+    description?: string;
+    required?: boolean;
+    schemaRef?: string;
+}
+export interface UniSpecRestMediaType {
+    schemaRef?: string;
+}
+export interface UniSpecRestContent {
+    [mediaType: string]: UniSpecRestMediaType;
+}
+export interface UniSpecRestRequestBody {
+    description?: string;
+    required?: boolean;
+    content?: UniSpecRestContent;
+}
+export interface UniSpecRestResponse {
+    description?: string;
+    content?: UniSpecRestContent;
+}
+export interface UniSpecRestRoute {
+    name?: string;
+    summary?: string;
+    description?: string;
+    path: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    pathParams?: UniSpecRestParameter[];
+    queryParams?: UniSpecRestParameter[];
+    headers?: UniSpecRestParameter[];
+    requestBody?: UniSpecRestRequestBody;
+    responses?: Record<string, UniSpecRestResponse>;
+    security?: UniSpecSecurityRequirement[];
+}
+export interface UniSpecRestProtocol {
+    routes?: UniSpecRestRoute[];
+    securitySchemes?: Record<string, Record<string, unknown>>;
+}
+export interface UniSpecSchemaDefinition {
+    jsonSchema: Record<string, unknown>;
+}
+export interface UniSpecSchemas {
+    [name: string]: UniSpecSchemaDefinition;
+}
+export interface UniSpecEnvironment {
+    name: string;
+    baseUrl: string;
+    region?: string;
+    labels?: Record<string, string>;
+    isDefault?: boolean;
 }
 export interface UniSpecServiceProtocols {
-    rest?: unknown;
+    rest?: UniSpecRestProtocol;
     graphql?: UniSpecGraphQLProtocol;
     websocket?: UniSpecWebSocketProtocol;
 }
@@ -39,7 +89,13 @@ export interface UniSpecService {
     name: string;
     title?: string;
     description?: string;
+    version?: string;
+    owner?: string;
+    tags?: string[];
+    links?: Record<string, string>;
     protocols?: UniSpecServiceProtocols;
+    schemas?: UniSpecSchemas;
+    environments?: UniSpecEnvironment[];
 }
 export interface UniSpecDocument {
     unispecVersion: string;
@@ -55,3 +111,88 @@ export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
 }
+export type UniSpecTestProtocol = "rest" | "graphql" | "websocket";
+export interface UniSpecTestTarget {
+    protocol: UniSpecTestProtocol;
+    operationId: string;
+    environment?: string;
+}
+export interface UniSpecRestTestParams {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+}
+export interface UniSpecRestTestRequest {
+    params?: UniSpecRestTestParams;
+    headers?: Record<string, unknown>;
+    body?: unknown;
+    authProfile?: string;
+}
+export type UniSpecRestExpectedStatus = number | number[];
+export type UniSpecRestBodyExpectationMode = "exact" | "contains" | "schemaOnly" | "snapshot";
+export interface UniSpecRestBodyExpectation {
+    mode?: UniSpecRestBodyExpectationMode;
+    json?: unknown;
+    schemaRef?: string;
+}
+export interface UniSpecRestTestExpect {
+    status: UniSpecRestExpectedStatus;
+    headers?: Record<string, unknown>;
+    body?: UniSpecRestBodyExpectation;
+}
+export interface UniSpecGraphQLTestRequest {
+    operationName?: string;
+    query: string;
+    variables?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+    authProfile?: string;
+}
+export interface UniSpecGraphQLTestExpect {
+    data?: unknown;
+    errors?: unknown;
+    bodyMode?: string;
+}
+export type UniSpecWebSocketTestMessageActionType = "send" | "expect";
+export interface UniSpecWebSocketTestMessageAction {
+    type: UniSpecWebSocketTestMessageActionType;
+    messageName: string;
+    payload?: unknown;
+}
+export interface UniSpecWebSocketTestRequest {
+    channel: string;
+    direction?: "publish" | "subscribe" | "both";
+    messages?: UniSpecWebSocketTestMessageAction[];
+    authProfile?: string;
+}
+export interface UniSpecWebSocketTestExpect {
+    messages?: UniSpecWebSocketTestMessageAction[];
+    timeoutMs?: number;
+}
+export interface UniSpecTestRequest {
+    rest?: UniSpecRestTestRequest;
+    graphql?: UniSpecGraphQLTestRequest;
+    websocket?: UniSpecWebSocketTestRequest;
+}
+export interface UniSpecTestExpect {
+    rest?: UniSpecRestTestExpect;
+    graphql?: UniSpecGraphQLTestExpect;
+    websocket?: UniSpecWebSocketTestExpect;
+}
+export interface UniSpecTestCase {
+    name: string;
+    description?: string;
+    target: UniSpecTestTarget;
+    request: UniSpecTestRequest;
+    expect: UniSpecTestExpect;
+    tags?: string[];
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecTestsDocument {
+    uniSpecTestsVersion: string;
+    target: {
+        serviceName: string;
+        serviceVersion?: string;
+        environment?: string;
+    };
+    tests: UniSpecTestCase[];
+    extensions?: Record<string, unknown>;
+}

package/dist/types/index.js

@@ -1 +1,2 @@
+// GraphQL protocol types
 export {};

package/dist/validator/index.d.ts

@@ -1,7 +1,11 @@
-import { UniSpecDocument, ValidationResult } from "../types";
+import { UniSpecDocument, UniSpecTestsDocument, ValidationResult } from "../types";
 export interface ValidateOptions {
 }
 /**
  * Validate a UniSpec document against the UniSpec JSON Schema.
  */
 export declare function validateUniSpec(doc: UniSpecDocument, _options?: ValidateOptions): Promise<ValidationResult>;
+/**
+ * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
+ */
+export declare function validateUniSpecTests(doc: UniSpecTestsDocument, _options?: ValidateOptions): Promise<ValidationResult>;

package/dist/validator/index.js

@@ -6,6 +6,8 @@ const ajv = new Ajv2020({
     allErrors: true,
     strict: true,
 });
+// Register minimal URI format to satisfy UniSpec schemas (service.environments[*].baseUrl)
+ajv.addFormat("uri", true);
 // Register all UniSpec subschemas so that Ajv can resolve internal $ref links
 try {
     const schemaRootPath = require.resolve("@unispechq/unispec-schema");
@@ -20,6 +22,7 @@ catch {
     // parts of the schema that do not rely on those $ref references.
 }
 const validateFn = ajv.compile(unispecSchema);
+let validateTestsFn;
 function mapAjvErrors(errors) {
     if (!errors)
         return [];
@@ -45,3 +48,25 @@ export async function validateUniSpec(doc, _options = {}) {
         errors: mapAjvErrors(validateFn.errors),
     };
 }
+/**
+ * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
+ */
+export async function validateUniSpecTests(doc, _options = {}) {
+    if (!validateTestsFn) {
+        const schemaRootPath = require.resolve("@unispechq/unispec-schema");
+        const schemaDir = schemaRootPath.replace(/index\.(cjs|mjs|js)$/u, "schema/");
+        const testsSchema = require(`${schemaDir}unispec-tests.schema.json`);
+        validateTestsFn = ajv.compile(testsSchema);
+    }
+    const valid = validateTestsFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateTestsFn.errors),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unispechq/unispec-core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Central UniSpec Core Engine providing parsing, validation, normalization, diffing, and conversion of UniSpec specs.",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
     "release:major": "node scripts/release.js major"
   },
   "dependencies": {
-    "@unispechq/unispec-schema": "^0.2.1",
+    "@unispechq/unispec-schema": "^0.3.1",
     "ajv": "^8.12.0"
   },
   "devDependencies": {