@unispechq/unispec-schema 0.3.3 → 0.3.5

package/README.md

@@ -111,6 +111,41 @@ The canonical, machine-readable definition of UniSpec lives in the schema/ direc
 - All examples must validate against the schema
 - Breaking changes require explicit agreement and a major version bump
 
+## Service Object
+
+The UniSpec document describes a single `service`.
+
+### `service` fields
+
+- **`name`** (required) — service identifier.
+- **`description`** (optional) — human-readable description.
+- **`version`** (optional) — service contract version (SemVer).
+- **`protocols`** (optional) — protocol-specific API surfaces (`rest`, `graphql`, `websocket`).
+- **`schemas`** (optional) — reusable schemas referenced by protocol definitions.
+
+### `schemaRef` convention
+
+Fields named `schemaRef` reference schemas defined in `service.schemas`.
+
+Recommended format:
+
+- `<SchemaName>` where `SchemaName` is a key in `service.schemas`.
+
+Tools may also accept a JSON Pointer form:
+
+- `#/service/schemas/<SchemaName>`
+
+### Protocol URLs
+
+GraphQL and WebSocket protocol definitions may include an optional `url` field.
+
+Recommended: relative path (e.g. `/graphql`, `/ws`). Absolute URLs are allowed only if the service is tightly bound to a single host.
+
+If omitted, tooling may assume common framework defaults:
+
+- GraphQL: `/graphql`
+- WebSocket: `/ws` (or `/socket.io` for Socket.IO)
+
 ## Examples
 
 The examples/ directory contains official UniSpec examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unispechq/unispec-schema",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Official UniSpec JSON Schemas",
   "type": "module",
   "main": "index.cjs",

package/schema/types/graphql.schema.json

@@ -28,6 +28,10 @@
     }
   },
   "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."

package/schema/types/rest.schema.json

@@ -93,7 +93,7 @@
         },
         "schemaRef": {
           "type": "string",
-          "description": "Reference to a reusable schema defined in the service-level schemas section."
+          "description": "Reference to a reusable schema defined in service.schemas. Recommended format: <SchemaName> (where SchemaName is a key in service.schemas). Tools may also accept a JSON Pointer in the form #/service/schemas/<SchemaName>."
         }
       },
       "additionalProperties": false
@@ -103,7 +103,7 @@
       "properties": {
         "schemaRef": {
           "type": "string",
-          "description": "Reference to a reusable schema used as the content payload."
+          "description": "Reference to a reusable schema defined in service.schemas used as the content payload. Recommended format: <SchemaName> (where SchemaName is a key in service.schemas). Tools may also accept a JSON Pointer in the form #/service/schemas/<SchemaName>."
         }
       },
       "additionalProperties": false

package/schema/types/websocket.schema.json

@@ -16,7 +16,7 @@
         },
         "schemaRef": {
           "type": "string",
-          "description": "Reference to a reusable schema describing the message payload."
+          "description": "Reference to a reusable schema describing the message payload. Recommended format: <SchemaName> (where SchemaName is a key in service.schemas). Tools may also accept a JSON Pointer in the form #/service/schemas/<SchemaName>."
         }
       },
       "additionalProperties": false
@@ -68,6 +68,10 @@
     }
   },
   "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/schema/unispec-tests.schema.json

@@ -205,7 +205,7 @@
         },
         "schemaRef": {
           "type": "string",
-          "description": "Reference to a schema from service.schemas for schemaOnly mode."
+          "description": "Reference to a schema from service.schemas for schemaOnly mode. Recommended format: <SchemaName> (where SchemaName is a key in service.schemas). Tools may also accept a JSON Pointer in the form #/service/schemas/<SchemaName>."
         }
       },
       "additionalProperties": false