UniSpec Core Engine

The official UniSpec Core Engine package — parser, validator, normalizer, diff engine for the UniSpec format

🚀 Quick Overview

UniSpec Core Engine is the central runtime package of the UniSpec ecosystem. It implements the mechanics of the UniSpec Format: loading, JSON Schema validation, normalization, and diffing.

This repository contains only the Core Engine, which is consumed by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs) that live in separate repositories.

Core Capabilities

• 🧠 Core Engine — parser, validator, normalizer, diff engine
• 📋 UniSpec Config — configuration file support for multi-service setups
• 🧩 Shared types and utilities — types and helper functions used across the UniSpec ecosystem

Protocol Support

UniSpec unifies documentation for:

• REST APIs
• GraphQL APIs
• WebSocket APIs
• Event-driven APIs (future)
• Multi-service architectures

🏁 Getting Started

Installation

npm install @unispechq/unispec-core

Basic Usage

import { validateUniSpec, loadUniSpec } from '@unispechq/unispec-core';

// Load and validate a UniSpec document
const spec = await loadUniSpec('./unispec.yaml');
const result = await validateUniSpec(spec);

if (result.valid) {
  console.log('✅ Valid UniSpec document');
} else {
  console.log('❌ Validation errors:', result.errors);
}

📚 Documentation

📖 Core Concepts

• UniSpec format overview
• Core Engine architecture
• Protocol coverage details
• Platform components explanation
• Use cases and deployment patterns

💡 Usage Examples

• Document validation
• Configuration support
• Schema reference resolution
• Enhanced diff analysis
• Performance optimization
• Error handling patterns

🔧 API Reference

• Complete function documentation
• Type definitions and interfaces
• Configuration options
• Error types and codes
• Performance considerations

🛠️ Development Guide

• Repository structure
• Development setup
• Testing guidelines
• Build process
• Contributing guidelines
• Plugin development

📦 Repository Structure

unispec-core/
├─ src/
│  ├─ loader/           # File loading with security
│  ├─ validator/        # JSON Schema validation
│  ├─ normalizer/       # Structure normalization
│  ├─ diff/             # Enhanced comparison
│  ├─ cache/            # LRU caching
│  ├─ types/            # TypeScript interfaces
│  └─ index.ts          # Public API
├─ tests/               # Unit and integration tests
├─ docs/                # Detailed documentation
└─ scripts/             # Build and release scripts

🤝 Contributing

Contributions are welcome! Before contributing, please review:

• Development Guide
• .windsurfrules

All core changes must comply with:

• the UniSpec format from unispec-spec
• compatibility rules
• test coverage
• platform architecture

📊 Related Repositories

| Repository | Purpose | |------------------------|---------| | unispec-spec | UniSpec format definition (schemas, examples) | | unispec-core | This repo — UniSpec Core Engine implementation | | unispec-docs | Documentation site | | unispec-js-adapters | Framework integrations (Express/Nest/Fastify) | | unispec-infra | Helm charts, Docker, Terraform for deployment |

📄 License

UniSpec Core Engine is open-source and free to use under the MIT License.

🔥 Summary

unispec-core is the heart of the UniSpec ecosystem at the code level. It provides the Core Engine used to validate, normalize, diff, and integrate API specifications in the UniSpec format.

If you're building tools, adapters, or platform services that rely on UniSpec → this is where the engine lives.

For detailed information, explore the documentation folder.