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

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 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
│  │     └─ bearer-token.json
│  └─ invalid/                       # Schema violations for testing
│     ├─ spec/                       # Invalid specifications
│     └─ config/                     # Invalid configurations
│
├─ 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 — Core API specification format
• UniSpec Tests — Executable test cases format
• UniSpec Config — Service discovery and configuration

Reference documentation

• reference/ — Detailed field-by-field reference, versioning, and style guides

Examples

The examples/ directory contains comprehensive examples in JSON format:

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
  • bearer-token.json — HTTP spec retrieval protected by Bearer token

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 for detailed documentation.

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

# 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.