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

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. The UniSpec format is designed to be an open standard.