@unispechq/unispec-schema 0.4.2 → 0.4.3

package/README.md

@@ -28,9 +28,20 @@ unispec-spec/
 │     ├─ 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
+├─ examples/          # Real-world examples in JSON format
+│  ├─ valid/                         # Conforming examples
+│  │  ├─ spec/                       # Valid UniSpec specifications
+│  │  │  ├─ rest-simple.json         # Simple REST API
+│  │  │  ├─ graphql-simple.json      # GraphQL API
+│  │  │  ├─ websocket-simple.json    # WebSocket API
+│  │  │  └─ mixed-complete.json      # Multi-protocol API
+│  │  └─ config/                     # Valid configuration files
+│  │     ├─ simple-multi-service.json
+│  │     ├─ registry-based.json
+│  │     └─ complete-enterprise.json
+│  └─ invalid/                       # Schema violations for testing
+│     ├─ spec/                       # Invalid specifications
+│     └─ config/                     # Invalid configurations
 │
 ├─ docs/              # Detailed format documentation
 │  ├─ unispec.md                     # UniSpec document format
@@ -112,14 +123,24 @@ The canonical, machine-readable definition of UniSpec lives in the schema/ direc
 
 ## 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
+The `examples/` directory contains comprehensive examples in JSON format:
 
-All examples are validated as part of CI.
+### Valid Examples (`examples/valid/`)
+- **Specifications** (`spec/`):
+  - `rest-simple.json` — Simple REST user management service
+  - `graphql-simple.json` — GraphQL blog service
+  - `websocket-simple.json` — WebSocket chat service  
+  - `mixed-complete.json` — Complete multi-protocol e-commerce service
+- **Configurations** (`config/`):
+  - `simple-multi-service.json` — Basic multi-service setup
+  - `registry-based.json` — Configuration using registry references
+  - `complete-enterprise.json` — Full enterprise configuration with environments
+
+### Invalid Examples (`examples/invalid/`)
+- **Specifications** — Various schema violations for testing validation
+- **Configurations** — Configuration validation errors
+
+All examples are validated as part of CI. See [`examples/README.md`](examples/README.md) for detailed documentation.
 
 ## Versioning
 

package/examples/README.md

@@ -1,128 +1,57 @@
 # UniSpec Examples
 
-This directory contains comprehensive examples for testing and validating UniSpec specifications.
+This directory contains example files demonstrating the UniSpec format and configuration.
 
 ## Structure
 
-### Valid Examples (`examples/valid/`)
+- `valid/` - Examples that conform to the UniSpec schema
+  - `spec/` - Valid UniSpec specification files
+  - `config/` - Valid UniSpec configuration files
+- `invalid/` - Examples that intentionally violate the schema for testing validation
+  - `spec/` - Invalid UniSpec specification files
+  - `config/` - Invalid UniSpec configuration files
 
-These examples demonstrate correct UniSpec usage and should pass validation:
+## Valid Examples
 
-#### 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
+### Specification Files (`valid/spec/`)
 
-#### 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
+- `rest-simple.json` - Simple REST API with user management
+- `graphql-simple.json` - Basic GraphQL blog service
+- `websocket-simple.json` - WebSocket chat service
+- `mixed-complete.json` - Complete e-commerce service with REST, GraphQL, and WebSocket
 
-#### 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
+### Configuration Files (`valid/config/`)
 
-#### 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
+- `simple-multi-service.json` - Basic multi-service configuration
+- `registry-based.json` - Configuration using registry references
+- `complete-enterprise.json` - Full enterprise configuration with environments
 
-#### 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
 
-### Invalid Examples (`examples/invalid/`)
+### Specification Files (`invalid/spec/`)
 
-These examples demonstrate common validation errors and should fail validation:
+- `missing-unispec-version.json` - Missing required `unispecVersion` field
+- `missing-service-name.json` - Missing required `service.name` field
+- `invalid-rest-method.json` - Invalid HTTP method in REST route
+- `graphql-missing-arg-type.json` - GraphQL argument missing type
+- `graphql-missing-name.json` - GraphQL operation missing name
+- `invalid-identifier.json` - Invalid identifier format
 
-#### 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
+### Configuration Files (`invalid/config/`)
 
-#### 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
+- `missing-version.json` - Missing required `version` field
+- `missing-services.json` - Missing required `services` array
+- `missing-service-name.json` - Service entry missing required `name` field
+- `invalid-spec-reference.json` - Invalid spec reference type
+- `empty-services-array.json` - Empty services array (violates minItems constraint)
 
-#### 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
+## Usage
 
-#### 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
+These examples are intended for:
 
-#### 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)
+1. **Learning** - Understanding the UniSpec format structure
+2. **Testing** - Validating UniSpec parsers and validators
+3. **Reference** - Starting points for creating your own specifications
+4. **Documentation** - Demonstrating various features and patterns
 
-## 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 {} \;
-```
+All examples are in JSON format for consistency and ease of validation against the JSON schemas.

package/examples/invalid/config/empty-services-array.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "services": []
+}

package/examples/invalid/config/invalid-spec-reference.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "test-service",
+      "baseUrl": "https://test.com",
+      "spec": {
+        "type": "invalid",
+        "url": "https://test.com/unispec.json"
+      }
+    }
+  ]
+}

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

@@ -1,22 +1,9 @@
-{
-	"unispecVersion": "0.1.0",
-	"service": {
-		"description": "Service without required name field",
-		"protocols": {
-			"rest": {
-				"routes": [
-					{
-						"name": "getUsers",
-						"path": "/users",
-						"method": "GET",
-						"responses": {
-							"200": {
-								"description": "Success"
-							}
-						}
-					}
-				]
-			}
-		}
-	}
+{
+  "version": 1,
+  "services": [
+    {
+      "baseUrl": "https://test.com",
+      "spec": "https://test.com/unispec.json"
+    }
+  ]
 }

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

@@ -0,0 +1,3 @@
+{
+  "version": 1
+}

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

@@ -1,6 +1,9 @@
-{
-	"service": {
-		"name": "config-api",
-		"description": "API missing required version field"
-	}
+{
+  "services": [
+    {
+      "name": "test-service",
+      "baseUrl": "https://test.com",
+      "spec": "https://test.com/unispec.json"
+    }
+  ]
 }

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

@@ -0,0 +1,21 @@
+{
+  "unispecVersion": "1.0.0",
+  "service": {
+    "name": "invalid-graphql-service",
+    "protocols": {
+      "graphql": {
+        "queries": [
+          {
+            "name": "user",
+            "args": [
+              {
+                "name": "id"
+              }
+            ],
+            "returnType": "User"
+          }
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "unispecVersion": "1.0.0",
+  "service": {
+    "name": "invalid-graphql-service",
+    "protocols": {
+      "graphql": {
+        "queries": [
+          {
+            "description": "Missing operation name",
+            "args": [
+              {
+                "name": "id",
+                "type": "ID!"
+              }
+            ],
+            "returnType": "User"
+          }
+        ]
+      }
+    }
+  }
+}

package/examples/invalid/spec/invalid-identifier.json

@@ -0,0 +1,23 @@
+{
+  "unispecVersion": "1.0.0",
+  "service": {
+    "name": "123invalid-service",
+    "description": "Invalid service name - starts with number",
+    "protocols": {
+      "rest": {
+        "routes": [
+          {
+            "name": "456invalid",
+            "path": "/test",
+            "method": "GET",
+            "responses": {
+              "200": {
+                "description": "OK"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/examples/invalid/spec/invalid-rest-method.json

@@ -0,0 +1,22 @@
+{
+  "unispecVersion": "1.0.0",
+  "service": {
+    "name": "invalid-rest-service",
+    "protocols": {
+      "rest": {
+        "routes": [
+          {
+            "name": "invalidMethod",
+            "path": "/test",
+            "method": "INVALID",
+            "responses": {
+              "200": {
+                "description": "OK"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "unispecVersion": "1.0.0",
+  "service": {
+    "description": "Missing required service name",
+    "protocols": {
+      "rest": {
+        "routes": [
+          {
+            "name": "test",
+            "path": "/test",
+            "method": "GET",
+            "responses": {
+              "200": {
+                "description": "OK"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/examples/invalid/spec/missing-unispec-version.json

@@ -0,0 +1,22 @@
+{
+  "service": {
+    "name": "invalid-service",
+    "description": "Missing unispecVersion field",
+    "protocols": {
+      "rest": {
+        "routes": [
+          {
+            "name": "test",
+            "path": "/test",
+            "method": "GET",
+            "responses": {
+              "200": {
+                "description": "OK"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/examples/valid/config/complete-enterprise.json

@@ -0,0 +1,142 @@
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "auth-service",
+      "baseUrl": "https://auth.company.com",
+      "spec": {
+        "type": "http",
+        "url": "/unispec.json"
+      },
+      "health": {
+        "path": "/health"
+      },
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Bearer token",
+          "required": true
+        },
+        {
+          "name": "X-Request-ID",
+          "description": "Request tracking ID",
+          "required": false
+        }
+      ],
+      "security": [
+        [
+          "oauth2"
+        ],
+        [
+          "apiKeyAuth"
+        ]
+      ]
+    },
+    {
+      "name": "catalog-service",
+      "baseUrl": "https://catalog.company.com",
+      "spec": {
+        "type": "file",
+        "path": "./specs/catalog.json"
+      },
+      "health": {
+        "path": "/ping"
+      },
+      "discovery": {
+        "dnsTemplate": "catalog-{env}.company.com"
+      }
+    },
+    {
+      "name": "notification-service",
+      "baseUrl": "https://notifications.company.com",
+      "spec": {
+        "type": "registry",
+        "ref": "notification-service@v2.1.0"
+      }
+    }
+  ],
+  "environments": [
+    {
+      "name": "development",
+      "overrides": {
+        "services": {
+          "auth-service": {
+            "baseUrl": "http://localhost:8000"
+          },
+          "catalog-service": {
+            "baseUrl": "http://localhost:8001"
+          }
+        }
+      },
+      "observability": {
+        "logging": {
+          "level": "debug"
+        },
+        "tracing": {
+          "enabled": true,
+          "samplingRate": 1
+        }
+      }
+    },
+    {
+      "name": "staging",
+      "overrides": {
+        "services": {
+          "auth-service": {
+            "baseUrl": "https://staging-auth.company.com"
+          }
+        }
+      },
+      "observability": {
+        "logging": {
+          "level": "info"
+        },
+        "metrics": {
+          "enabled": true,
+          "endpoints": [
+            "/metrics"
+          ]
+        }
+      },
+      "deployment": {
+        "kubernetes": {
+          "namespace": "staging",
+          "replicas": 2
+        }
+      }
+    },
+    {
+      "name": "production",
+      "observability": {
+        "logging": {
+          "level": "warn",
+          "format": "json"
+        },
+        "metrics": {
+          "enabled": true
+        },
+        "tracing": {
+          "enabled": true,
+          "samplingRate": 0.01
+        }
+      },
+      "deployment": {
+        "kubernetes": {
+          "namespace": "production",
+          "replicas": 5,
+          "serviceType": "LoadBalancer"
+        }
+      },
+      "dataResidency": "EU-West",
+      "audit": {
+        "enabled": true,
+        "retention": "1 year",
+        "fields": [
+          "userId",
+          "action",
+          "timestamp"
+        ]
+      }
+    }
+  ]
+}

package/examples/valid/config/registry-based.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "payment-service",
+      "baseUrl": "https://payments.example.com",
+      "spec": {
+        "type": "registry",
+        "ref": "payment-service@v1.2.3"
+      },
+      "headers": [
+        {
+          "name": "X-API-Key",
+          "description": "API key for payment service",
+          "required": true
+        }
+      ],
+      "security": [
+        [
+          "apiKeyAuth"
+        ]
+      ]
+    }
+  ],
+  "discovery": {
+    "dnsTemplate": "{service}.{env}.example.com"
+  },
+  "environments": [
+    {
+      "name": "staging",
+      "overrides": {
+        "services": {
+          "payment-service": {
+            "baseUrl": "https://staging-payments.example.com"
+          }
+        }
+      }
+    }
+  ]
+}

package/examples/valid/config/simple-multi-service.json

@@ -0,0 +1,58 @@
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "user-service",
+      "baseUrl": "https://user-api.example.com",
+      "spec": {
+        "type": "http",
+        "url": "https://user-api.example.com/unispec.json"
+      },
+      "health": {
+        "path": "/health"
+      }
+    },
+    {
+      "name": "order-service",
+      "baseUrl": "https://order-api.example.com",
+      "spec": {
+        "type": "file",
+        "path": "./order-service-spec.json"
+      },
+      "health": {
+        "path": "/ping"
+      }
+    }
+  ],
+  "environments": [
+    {
+      "name": "development",
+      "overrides": {
+        "services": {
+          "user-service": {
+            "baseUrl": "http://localhost:3001"
+          },
+          "order-service": {
+            "baseUrl": "http://localhost:3002"
+          }
+        }
+      }
+    },
+    {
+      "name": "production",
+      "observability": {
+        "logging": {
+          "level": "info",
+          "format": "json"
+        },
+        "metrics": {
+          "enabled": true
+        },
+        "tracing": {
+          "enabled": true,
+          "samplingRate": 0.1
+        }
+      }
+    }
+  ]
+}