@unispechq/unispec-schema 0.3.1 → 0.3.4

package/README.md

@@ -1,167 +1,196 @@
-# UniSpec Specification
-
-Official specification of the UniSpec API definition language
-
-## Overview
-
-UniSpec is a modern, multi-protocol API specification format designed to unify REST, GraphQL, WebSocket, and event-driven API documentation under a single, consistent model.
-
-This repository is the single source of truth for the UniSpec format.
-It contains everything required to understand, validate, and evolve the language:
-
-- Machine-readable JSON Schemas
-- Human-readable reference documentation
-- Official examples (REST, GraphQL, WebSocket, mixed APIs)
-- Versioning and compatibility rules
-- Documented process for evolving the format over time
-
-UniSpec powers all components of the UniSpec platform:
-Core Engine → CLI → Framework Adapters → Registry → Portal → Enterprise extensions.
-
-## Repository Structure
-```pgsql
-unispec-spec/
-├─ schema/            # JSON Schemas defining the UniSpec format
-│  ├─ unispec.schema.json
-│  └─ types/
-│     ├─ service.schema.json
-│     ├─ rest.schema.json
-│     ├─ graphql.schema.json
-│     ├─ websocket.schema.json
-│     ├─ schemas.schema.json
-│     └─ common.schema.json
-│
-├─ examples/          # Real-world examples in YAML/JSON
-│  ├─ simple-rest.yaml
-│  ├─ graphql.yaml
-│  ├─ websocket.yaml
-│  └─ mixed-api.yaml
-│
-├─ reference/         # Human-readable format documentation
-│  ├─ fields.md
-│  ├─ components.md
-│  ├─ versioning.md
-│  └─ style-guide.md
-│
-├─ CHANGELOG.md       # Release notes for UniSpec format versions
-└─ README.md
-```
-
-## Purpose of This Repository
-
-This repo defines the UniSpec language, not its implementation.
-
-### This repository contains:
-
-- Format specification
-- JSON Schemas
-- Examples and documentation
-- Rules for versioning and compatibility
-- Documented process for evolving the format over time
-
-### This repository does NOT contain:
-
-- UniSpec Core engine
-- CLI implementation
-- Framework adapters
-- Portal or Registry code
-- Runtime logic
-
-These live in other repositories of the UniSpec organization.
-
-## Format Philosophy
-
-UniSpec is built on the following principles:
-
-1. Multi-protocol by design
-- One format supports:
-- REST
-- GraphQL
-- WebSocket
-- (future) gRPC, AsyncAPI, message buses
-
-2. Developer-first
-- Readable YAML for humans, strict JSON Schema for machines.
-
-3. Strong structure, minimal ambiguity
-- No vague fields or implicit semantics.
-- Every field has a precise definition and validation rules.
-
-4. Extensible
-- Supports custom extensions via x-extensions, similar to OpenAPI but cleaner and more consistent.
-
-5. Transparent evolution
-- All major changes must be clearly documented.
-- Minor changes and clarifications must maintain backward compatibility.
-
-## JSON Schema
-
-The canonical, machine-readable definition of UniSpec lives in the schema/ directory.
-
-### Rules:
-
-- Must follow JSON Schema Draft 2020-12
-- Must use $defs for reusable components
-- Must clearly describe field semantics and constraints
-- All examples must validate against the schema
-- Breaking changes require explicit agreement and a major version bump
-
-## Examples
-
-The examples/ directory contains official UniSpec examples:
-
-- simple-rest.yaml — minimal REST service
-- graphql.yaml — example of a GraphQL API
-- websocket.yaml — WebSocket channels and messages
-- mixed-api.yaml — service combining REST + GraphQL + WebSocket
-
-All examples are validated as part of CI to ensure correctness.
-
-## Reference Documentation
-
-All human-readable format documentation lives in reference/:
-
-- fields.md — detailed field-by-field description
-- components.md — rules for schema composition and references
-- versioning.md — semantic versioning guidelines
-- style-guide.md — recommended naming and structuring conventions
-
-These documents must be kept in sync with schema changes.
-
-## Versioning
-
-UniSpec follows Semantic Versioning (SemVer):
-
-- MAJOR — breaking changes
-- MINOR — new backward-compatible features
-- PATCH — fixes, clarifications, corrections
-
-All changes must be recorded in CHANGELOG.md.
-
-## Format Changes and Contributions
-
-Any change that alters:
-
-- structure of the UniSpec format
-- semantics of existing fields
-- compatibility rules
-- supported protocols
-
-should be proposed and discussed in a pull request before being applied here.
-
-## Contributing
-
-Contributions are welcome!
-
-To contribute:
-
-1. Read the reference docs.
-2. Discuss substantial format changes in an issue or pull request.
-3. Submit a PR with clear explanation and schema validation.
-
-All contributions must preserve backward compatibility unless explicitly approved otherwise.
-
-## License
-
-This repository is open-source and free to implement.
+# UniSpec Specification
+
+Official specification of the UniSpec API definition language
+
+## Overview
+
+UniSpec is a modern, multi-protocol API specification format designed to unify REST, GraphQL, WebSocket, and event-driven API documentation under a single, consistent model.
+
+This repository is the single source of truth for the UniSpec format.
+It contains everything required to understand, validate, and evolve the language:
+
+- Machine-readable JSON Schemas
+- Human-readable reference documentation
+- Official examples (REST, GraphQL, WebSocket, mixed APIs)
+- A companion test specification (UniSpec Tests) for executable test documents
+- Versioning and compatibility rules
+- Documented process for evolving the format over time
+
+UniSpec powers all components of the UniSpec platform:
+Core Engine → CLI → Framework Adapters → Registry → Portal → Enterprise extensions.
+
+## Repository Structure
+```pgsql
+unispec-spec/
+├─ schema/            # JSON Schemas defining the UniSpec format
+│  ├─ unispec.schema.json          # Core UniSpec document
+│  ├─ unispec-tests.schema.json    # UniSpec Tests document (executable test cases)
+│  └─ types/
+│     ├─ service.schema.json
+│     ├─ rest.schema.json
+│     ├─ graphql.schema.json
+│     ├─ websocket.schema.json
+│     ├─ schemas.schema.json
+│     └─ common.schema.json
+│
+├─ examples/          # Real-world examples in YAML/JSON
+│  ├─ simple-rest.yaml
+│  ├─ graphql.yaml
+│  ├─ websocket.yaml
+│  ├─ mixed-api.yaml
+│  ├─ rest-with-schemas.yaml        # REST service using service.schemas and schemaRef
+│  └─ rest-with-schemas.tests.yaml  # UniSpec Tests for the same REST service
+│
+├─ reference/         # Human-readable format documentation
+│  ├─ fields.md
+│  ├─ components.md
+│  ├─ versioning.md
+│  ├─ style-guide.md
+│  └─ tests.md        # UniSpec Tests format reference
+│
+├─ CHANGELOG.md       # Release notes for UniSpec format versions
+└─ README.md
+```
+
+## Purpose of This Repository
+
+This repo defines the UniSpec language, not its implementation.
+
+### This repository contains:
+
+- Format specification
+- JSON Schemas
+- Examples and documentation
+- Rules for versioning and compatibility
+- Documented process for evolving the format over time
+
+### This repository does NOT contain:
+
+- UniSpec Core engine
+- CLI implementation
+- Framework adapters
+- Portal or Registry code
+- Runtime logic
+
+These live in other repositories of the UniSpec organization.
+
+## Format Philosophy
+
+UniSpec is built on the following principles:
+
+1. Multi-protocol by design
+- One format supports:
+- REST
+- GraphQL
+- WebSocket
+- (future) gRPC, AsyncAPI, message buses
+
+2. Developer-first
+- Readable YAML for humans, strict JSON Schema for machines.
+
+3. Strong structure, minimal ambiguity
+- No vague fields or implicit semantics.
+- Every field has a precise definition and validation rules.
+
+4. Extensible
+- Supports custom extensions via x-extensions, similar to OpenAPI but cleaner and more consistent.
+
+5. Transparent evolution
+- All major changes must be clearly documented.
+- Minor changes and clarifications must maintain backward compatibility.
+
+## JSON Schema
+
+The canonical, machine-readable definition of UniSpec lives in the schema/ directory.
+
+### Rules:
+
+- Must follow JSON Schema Draft 2020-12
+- Must use $defs for reusable components
+- Must clearly describe field semantics and constraints
+- 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>`
+
+## Examples
+
+The examples/ directory contains official UniSpec examples:
+
+- simple-rest.yaml — minimal REST service
+- graphql.yaml — example of a GraphQL API
+- websocket.yaml — WebSocket channels and messages
+- mixed-api.yaml — service combining REST + GraphQL + WebSocket
+
+All examples are validated as part of CI to ensure correctness.
+
+## Reference Documentation
+
+All human-readable format documentation lives in reference/:
+
+- fields.md — detailed field-by-field description
+- components.md — rules for schema composition and references
+- versioning.md — semantic versioning guidelines
+- style-guide.md — recommended naming and structuring conventions
+
+These documents must be kept in sync with schema changes.
+
+## Versioning
+
+UniSpec follows Semantic Versioning (SemVer):
+
+- MAJOR — breaking changes
+- MINOR — new backward-compatible features
+- PATCH — fixes, clarifications, corrections
+
+All changes must be recorded in CHANGELOG.md.
+
+## Format Changes and Contributions
+
+Any change that alters:
+
+- structure of the UniSpec format
+- semantics of existing fields
+- compatibility rules
+- supported protocols
+
+should be proposed and discussed in a pull request before being applied here.
+
+## Contributing
+
+Contributions are welcome!
+
+To contribute:
+
+1. Read the reference docs.
+2. Discuss substantial format changes in an issue or pull request.
+3. Submit a PR with clear explanation and schema validation.
+
+All contributions must preserve backward compatibility unless explicitly approved otherwise.
+
+## License
+
+This repository is open-source and free to implement.
 The UniSpec format is designed to be an open standard.

package/index.cjs

@@ -1,7 +1,7 @@
-const unispec = require("./schema/unispec.schema.json");
-const manifest = require("./schema/index.json");
-
-module.exports = {
-  unispec,
-  manifest,
-};
+const unispec = require("./schema/unispec.schema.json");
+const manifest = require("./schema/index.json");
+
+module.exports = {
+  unispec,
+  manifest,
+};

package/index.d.ts

@@ -1,9 +1,9 @@
-export const unispec: Record<string, any>;
-export const manifest: Record<string, any>;
-
-declare const _default: {
-  unispec: typeof unispec;
-  manifest: typeof manifest;
-};
-
-export default _default;
+export const unispec: Record<string, any>;
+export const manifest: Record<string, any>;
+
+declare const _default: {
+  unispec: typeof unispec;
+  manifest: typeof manifest;
+};
+
+export default _default;

package/index.mjs

@@ -1,9 +1,9 @@
-import { createRequire } from "module";
-
-const require = createRequire(import.meta.url);
-
-const unispec = require("./schema/unispec.schema.json");
-const manifest = require("./schema/index.json");
-
-export { unispec, manifest };
-export default { unispec, manifest };
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+
+const unispec = require("./schema/unispec.schema.json");
+const manifest = require("./schema/index.json");
+
+export { unispec, manifest };
+export default { unispec, manifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unispechq/unispec-schema",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "Official UniSpec JSON Schemas",
   "type": "module",
   "main": "index.cjs",
@@ -31,12 +31,19 @@
     "type": "git",
     "url": "git+https://github.com/unispec/unispec-spec.git"
   },
+  "bugs": {
+    "url": "https://github.com/unispec/unispec-spec/issues"
+  },
+  "homepage": "https://github.com/unispec/unispec-spec#readme",
   "keywords": [
     "unispec",
     "api",
     "json-schema",
     "specification"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "access": "public"
   }

package/schema/index.json

@@ -1,14 +1,14 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "@unispechq/unispec-schema",
-  "description": "Official UniSpec JSON Schemas",
-  "root": "./unispec.schema.json",
-  "types": {
-    "common": "./types/common.schema.json",
-    "graphql": "./types/graphql.schema.json",
-    "rest": "./types/rest.schema.json",
-    "schemas": "./types/schemas.schema.json",
-    "service": "./types/service.schema.json",
-    "websocket": "./types/websocket.schema.json"
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "@unispechq/unispec-schema",
+  "description": "Official UniSpec JSON Schemas",
+  "root": "./unispec.schema.json",
+  "types": {
+    "common": "./types/common.schema.json",
+    "graphql": "./types/graphql.schema.json",
+    "rest": "./types/rest.schema.json",
+    "schemas": "./types/schemas.schema.json",
+    "service": "./types/service.schema.json",
+    "websocket": "./types/websocket.schema.json"
+  }
+}

package/schema/types/common.schema.json

@@ -1,16 +1,16 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unispec.dev/schema/types/common.schema.json",
-  "title": "Common UniSpec definitions",
-  "$defs": {
-    "Identifier": {
-      "type": "string",
-      "description": "Identifier for services, operations, channels, etc.",
-      "pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
-    },
-    "Description": {
-      "type": "string",
-      "description": "Human-readable description text."
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unispec.dev/schema/types/common.schema.json",
+  "title": "Common UniSpec definitions",
+  "$defs": {
+    "Identifier": {
+      "type": "string",
+      "description": "Identifier for services, operations, channels, etc.",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
+    },
+    "Description": {
+      "type": "string",
+      "description": "Human-readable description text."
+    }
+  }
+}

package/schema/types/graphql.schema.json

@@ -1,58 +1,58 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unispec.dev/schema/types/graphql.schema.json",
-  "title": "GraphQL API surface",
-  "type": "object",
-  "$defs": {
-    "Operation": {
-      "type": "object",
-      "required": ["name"],
-      "properties": {
-        "name": {
-          "$ref": "./common.schema.json#/$defs/Identifier"
-        },
-        "description": {
-          "$ref": "./common.schema.json#/$defs/Description"
-        },
-        "deprecated": {
-          "type": "boolean",
-          "description": "Marks the operation as deprecated.",
-          "default": false
-        },
-        "deprecationReason": {
-          "type": "string",
-          "description": "Human-readable reason for deprecation."
-        }
-      },
-      "additionalProperties": false
-    }
-  },
-  "properties": {
-    "schema": {
-      "type": "string",
-      "description": "GraphQL schema SDL as a string. Canonical source of type definitions."
-    },
-    "queries": {
-      "type": "array",
-      "description": "Query operations exposed by the GraphQL API.",
-      "items": {
-        "$ref": "#/$defs/Operation"
-      }
-    },
-    "mutations": {
-      "type": "array",
-      "description": "Mutation operations exposed by the GraphQL API.",
-      "items": {
-        "$ref": "#/$defs/Operation"
-      }
-    },
-    "subscriptions": {
-      "type": "array",
-      "description": "Subscription operations exposed by the GraphQL API.",
-      "items": {
-        "$ref": "#/$defs/Operation"
-      }
-    }
-  },
-  "additionalProperties": false
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unispec.dev/schema/types/graphql.schema.json",
+  "title": "GraphQL API surface",
+  "type": "object",
+  "$defs": {
+    "Operation": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "$ref": "./common.schema.json#/$defs/Identifier"
+        },
+        "description": {
+          "$ref": "./common.schema.json#/$defs/Description"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Marks the operation as deprecated.",
+          "default": false
+        },
+        "deprecationReason": {
+          "type": "string",
+          "description": "Human-readable reason for deprecation."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "schema": {
+      "type": "string",
+      "description": "GraphQL schema SDL as a string. Canonical source of type definitions."
+    },
+    "queries": {
+      "type": "array",
+      "description": "Query operations exposed by the GraphQL API.",
+      "items": {
+        "$ref": "#/$defs/Operation"
+      }
+    },
+    "mutations": {
+      "type": "array",
+      "description": "Mutation operations exposed by the GraphQL API.",
+      "items": {
+        "$ref": "#/$defs/Operation"
+      }
+    },
+    "subscriptions": {
+      "type": "array",
+      "description": "Subscription operations exposed by the GraphQL API.",
+      "items": {
+        "$ref": "#/$defs/Operation"
+      }
+    }
+  },
+  "additionalProperties": false
+}