@unispechq/unispec-schema 0.4.0 → 0.4.2

package/README.md

@@ -1,163 +1,171 @@
-# 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
-## 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
-│  ├─ unispec-config.schema.json   # UniSpec Config document
-│  └─ types/                       # Shared schema types
-│     ├─ common.schema.json       # Common definitions
-│     ├─ service.schema.json      # Service definition
-│     ├─ rest.schema.json          # REST protocol
-│     ├─ graphql.schema.json       # GraphQL protocol
-│     ├─ websocket.schema.json     # WebSocket protocol
-│     └─ schemas.schema.json       # Reusable schemas
-│
-├─ examples/          # Real-world examples in YAML/JSON
-│  ├─ *.yaml                         # UniSpec document examples
-│  └─ unispec.config.json            # Config example
-│
-├─ docs/              # Detailed format documentation
-│  ├─ unispec.md                     # UniSpec document format
-│  ├─ unispec-tests.md               # UniSpec Tests format
-│  └─ unispec-config.md              # UniSpec Config format
-│
-├─ reference/         # Human-readable reference docs
-│  ├─ fields.md                     # Complete field reference
-│  ├─ versioning.md                 # Versioning guidelines
-│  └─ style-guide.md                # Documentation style guide
-└─ CHANGELOG.md       # Release notes
-```
-
-## 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
-
-## Documentation
-
-### Format specifications
-- **[UniSpec Document](docs/unispec.md)** — Core API specification format
-- **[UniSpec Tests](docs/unispec-tests.md)** — Executable test cases format
-- **[UniSpec Config](docs/unispec-config.md)** — Service discovery and configuration
-
-### Reference documentation
-- `reference/` — Detailed field-by-field reference, versioning, and style guides
-
-## Examples
-
-The `examples/` directory contains official examples:
-- `simple-rest.yaml` — minimal REST service
-- `graphql.yaml` — GraphQL API
-- `websocket.yaml` — WebSocket channels
-- `mixed-api.yaml` — multi-protocol service
-- `unispec.config.json` — configuration example
-
-All examples are validated as part of CI.
-
-## 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
+## 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
+│  ├─ unispec-config.schema.json   # UniSpec Config document
+│  └─ types/                       # Shared schema types
+│     ├─ common.schema.json       # Common definitions
+│     ├─ service.schema.json      # Service definition
+│     ├─ rest.schema.json          # REST protocol
+│     ├─ graphql.schema.json       # GraphQL protocol
+│     ├─ websocket.schema.json     # WebSocket protocol
+│     └─ schemas.schema.json       # Reusable schemas
+│
+├─ examples/          # Real-world examples in YAML/JSON
+│  ├─ *.yaml                         # UniSpec document examples
+│  └─ unispec.config.json            # Config example
+│
+├─ docs/              # Detailed format documentation
+│  ├─ unispec.md                     # UniSpec document format
+│  ├─ unispec-tests.md               # UniSpec Tests format
+│  └─ unispec-config.md              # UniSpec Config format
+│
+├─ reference/         # Human-readable reference docs
+│  ├─ fields.md                     # Complete field reference
+│  ├─ versioning.md                 # Versioning guidelines
+│  └─ style-guide.md                # Documentation style guide
+└─ CHANGELOG.md       # Release notes
+```
+
+## 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. 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
+
+## Documentation
+
+### Format specifications
+- **[UniSpec Document](docs/unispec.md)** — Core API specification format
+- **[UniSpec Tests](docs/unispec-tests.md)** — Executable test cases format
+- **[UniSpec Config](docs/unispec-config.md)** — Service discovery and configuration
+
+### Reference documentation
+- `reference/` — Detailed field-by-field reference, versioning, and style guides
+
+## Examples
+
+The `examples/` directory contains official examples:
+- `simple-rest.yaml` — minimal REST service
+- `graphql.yaml` — GraphQL API
+- `websocket.yaml` — WebSocket channels
+- `mixed-api.yaml` — multi-protocol service
+- `unispec.config.json` — configuration example
+
+All examples are validated as part of CI.
+
+## 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.
+
+## Installation
+
+```bash
+# Install dependencies with pnpm
+pnpm install
+
+# Or with npm (legacy support)
+npm install
+```
+
+## Contributing
+
+Contributions are welcome!
+
+To contribute:
+
+1. Install dependencies: `pnpm install`
+2. Read the reference docs.
+3. Discuss substantial format changes in an issue or pull request.
+4. 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/examples/README.md

@@ -0,0 +1,128 @@
+# UniSpec Examples
+
+This directory contains comprehensive examples for testing and validating UniSpec specifications.
+
+## Structure
+
+### Valid Examples (`examples/valid/`)
+
+These examples demonstrate correct UniSpec usage and should pass validation:
+
+#### REST API Examples
+- **`rest-complete.json`** - Complete user management API with authentication, pagination, schemas, and comprehensive error handling
+- **`rest-simple.json`** - Simple blog API with basic CRUD operations
+
+#### GraphQL API Examples  
+- **`graphql-complete.json`** - Full-featured GraphQL API with users, posts, authentication, queries, mutations, and subscriptions
+- **`graphql-simple.json`** - Minimal GraphQL API for blog posts
+
+#### WebSocket API Examples
+- **`websocket-complete.json`** - Real-time chat API with multiple channels, authentication, reconnection strategies, and comprehensive message types
+- **`websocket-simple.json`** - Simple notification and status update WebSocket API
+
+#### Mixed Protocol Examples
+- **`mixed-complete.json`** - Complete social media platform with REST (media upload), GraphQL (social features), and WebSocket (real-time updates)
+- **`mixed-simple.json`** - Simple API combining REST and GraphQL protocols
+
+#### Configuration Examples
+- **`config/complete.json`** - Complete configuration with multiple services, environments, auth, and health checks
+- **`config/minimal.json`** - Minimal configuration with single service
+- **`config/unispec.config.json`** - Existing configuration example (JSON format)
+
+### Invalid Examples (`examples/invalid/`)
+
+These examples demonstrate common validation errors and should fail validation:
+
+#### REST API Validation Errors
+- **`rest-missing-required.json`** - Missing required fields (service name, route path)
+- **`rest-invalid-method.json`** - Invalid HTTP method
+- **`rest-invalid-identifiers.json`** - Invalid identifier patterns with spaces
+- **`rest-additional-properties.json`** - Additional properties not allowed by schema
+
+#### GraphQL API Validation Errors
+- **`graphql-missing-schema.json`** - Missing required schema field
+- **`graphql-missing-name.json`** - Missing required operation name
+- **`graphql-missing-arg-type.json`** - Missing required argument type
+- **`graphql-additional-properties.json`** - Additional properties not allowed
+
+#### WebSocket API Validation Errors
+- **`websocket-missing-channel-name.json`** - Missing required channel name
+- **`websocket-missing-message-name.json`** - Missing required message name
+- **`websocket-invalid-direction.json`** - Invalid direction enum values
+- **`websocket-additional-properties.json`** - Additional properties not allowed
+
+#### Mixed Protocol Validation Errors
+- **`mixed-missing-graphql-schema.json`** - GraphQL protocol missing required schema
+- **`mixed-invalid-protocol.json`** - Invalid protocol property
+- **`mixed-multiple-errors.json`** - Multiple validation errors across protocols
+
+#### Configuration Validation Errors
+- **`config/missing-version.json`** - Missing required version field
+- **`config/missing-service-name.json`** - Service without required name field
+- **`config/additional-properties.json`** - Additional properties not allowed
+- **`config/unispec.config.json`** - Existing configuration example (for reference)
+
+## Usage in npm
+
+These examples are published as part of the `@unispechq/unispec-schema` package and can be imported:
+
+```javascript
+// Import all valid examples
+import validExamples from '@unispechq/unispec-schema/examples/valid';
+
+// Import specific example
+import restComplete from '@unispechq/unispec-schema/examples/valid/rest-complete';
+
+// Import invalid examples for testing validation
+import invalidExamples from '@unispechq/unispec-schema/examples/invalid';
+```
+
+## Testing
+
+Use these examples to test your UniSpec validation tools:
+
+1. **Positive Testing**: Use valid examples to ensure your validator accepts correct specifications
+2. **Negative Testing**: Use invalid examples to ensure your validator catches errors appropriately
+3. **Edge Case Testing**: Test boundary conditions and complex scenarios with the complete examples
+4. **Protocol Testing**: Validate specific protocol handling with individual REST, GraphQL, and WebSocket examples
+
+## Coverage
+
+The examples cover:
+
+- ✅ All UniSpec protocols (REST, GraphQL, WebSocket)
+- ✅ Authentication and security schemes
+- ✅ Schema definitions and references
+- ✅ Error handling and responses
+- ✅ Pagination and filtering
+- ✅ Real-time communication patterns
+- ✅ Mixed protocol architectures
+- ✅ Configuration management (YAML and JSON)
+- ✅ Environment-specific configurations
+- ✅ Service discovery and health checks
+- ✅ Common validation errors
+- ✅ Edge cases and complex scenarios
+
+## Contributing
+
+When adding new examples:
+
+1. Place valid examples in `examples/valid/`
+2. Place invalid examples in `examples/invalid/`
+3. Use descriptive filenames
+4. Add comments explaining the purpose of the example
+5. Update this README file
+6. Update `package.json` exports if adding new files
+7. Test against the UniSpec schema
+
+## Schema Validation
+
+All examples should be validated against the UniSpec JSON Schema:
+
+```bash
+# Validate a specific example
+npx ajv validate -s schema/unispec.schema.json -d examples/valid/rest-complete.json
+
+# Validate all examples
+find examples -name "*.json" -exec npx ajv validate -s schema/unispec.schema.json -d {} \;
+```

package/examples/invalid/config/additional-properties.json

@@ -0,0 +1,26 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "config-api",
+		"description": "API with additional properties",
+		"invalidProperty": "should not exist",
+		"protocols": {
+			"rest": {
+				"routes": [
+					{
+						"name": "getUsers",
+						"path": "/users",
+						"method": "GET",
+						"responses": {
+							"200": {
+								"description": "Success",
+								"invalidProperty": "should not exist"
+							}
+						}
+					}
+				],
+				"invalidProperty": "should not exist"
+			}
+		}
+	}
+}

package/examples/invalid/config/missing-service-name.json

@@ -0,0 +1,22 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"description": "Service without required name field",
+		"protocols": {
+			"rest": {
+				"routes": [
+					{
+						"name": "getUsers",
+						"path": "/users",
+						"method": "GET",
+						"responses": {
+							"200": {
+								"description": "Success"
+							}
+						}
+					}
+				]
+			}
+		}
+	}
+}

package/examples/invalid/config/missing-version.json

@@ -0,0 +1,6 @@
+{
+	"service": {
+		"name": "config-api",
+		"description": "API missing required version field"
+	}
+}

package/examples/invalid/graphql-additional-properties.json

@@ -0,0 +1,22 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "invalid-graphql-api",
+		"description": "GraphQL API with additional properties",
+		"protocols": {
+			"graphql": {
+				"url": "/graphql",
+				"schema": "type Query {\n  users: [User!]!\n}\n\ntype User {\n  id: ID!\n  name: String!\n}\n",
+				"queries": [
+					{
+						"name": "users",
+						"description": "Get users",
+						"returnType": "[User!]!",
+						"invalidProperty": "should not exist"
+					}
+				],
+				"invalidProperty": "should not exist"
+			}
+		}
+	}
+}

package/examples/invalid/graphql-missing-arg-type.json

@@ -0,0 +1,26 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "invalid-graphql-api",
+		"description": "GraphQL API with missing argument type",
+		"protocols": {
+			"graphql": {
+				"url": "/graphql",
+				"schema": "type Query {\n  users(limit: Int): [User!]!\n}\n\ntype User {\n  id: ID!\n  name: String!\n}\n",
+				"queries": [
+					{
+						"name": "users",
+						"description": "Get users",
+						"args": [
+							{
+								"name": "limit",
+								"description": "Limit number of results"
+							}
+						],
+						"returnType": "[User!]!"
+					}
+				]
+			}
+		}
+	}
+}

package/examples/invalid/graphql-missing-name.json

@@ -0,0 +1,19 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "invalid-graphql-api",
+		"description": "GraphQL API with missing operation name",
+		"protocols": {
+			"graphql": {
+				"url": "/graphql",
+				"schema": "type Query {\n  users: [User!]!\n}\n\ntype User {\n  id: ID!\n  name: String!\n}\n",
+				"queries": [
+					{
+						"description": "Get users",
+						"returnType": "[User!]!"
+					}
+				]
+			}
+		}
+	}
+}

package/examples/invalid/graphql-missing-schema.json

@@ -0,0 +1,19 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "invalid-graphql-api",
+		"description": "GraphQL API missing required schema field",
+		"protocols": {
+			"graphql": {
+				"url": "/graphql",
+				"queries": [
+					{
+						"name": "users",
+						"description": "Get users",
+						"returnType": "[User!]!"
+					}
+				]
+			}
+		}
+	}
+}

package/examples/invalid/mixed-invalid-protocol.json

@@ -0,0 +1,26 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "invalid-mixed-api",
+		"description": "Mixed protocol API with invalid protocol",
+		"protocols": {
+			"rest": {
+				"routes": [
+					{
+						"name": "getUsers",
+						"path": "/users",
+						"method": "GET",
+						"responses": {
+							"200": {
+								"description": "Success"
+							}
+						}
+					}
+				]
+			},
+			"invalidProtocol": {
+				"someProperty": "value"
+			}
+		}
+	}
+}

package/examples/invalid/mixed-missing-graphql-schema.json

@@ -0,0 +1,33 @@
+{
+	"unispecVersion": "0.1.0",
+	"service": {
+		"name": "invalid-mixed-api",
+		"description": "Mixed protocol API missing GraphQL schema",
+		"protocols": {
+			"rest": {
+				"routes": [
+					{
+						"name": "getUsers",
+						"path": "/users",
+						"method": "GET",
+						"responses": {
+							"200": {
+								"description": "Success"
+							}
+						}
+					}
+				]
+			},
+			"graphql": {
+				"url": "/graphql",
+				"queries": [
+					{
+						"name": "users",
+						"description": "Get users",
+						"returnType": "[User!]!"
+					}
+				]
+			}
+		}
+	}
+}