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.

$3

- 🧠 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

$3

UniSpec unifies documentation for:
- REST APIs
- GraphQL APIs
- WebSocket APIs
- Event-driven APIs (future)
- Multi-service architectures

---

🏁 Getting Started

$3

``bash
npm install @unispechq/unispec-core
`

$3

`javascript
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

$3

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

$3

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

$3

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

$3

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