0.0.1 • Published 4 months ago
slimspec v0.0.1
/$$$$$$ /$$ /$$ /$$$$$$
/$$__ $$| $$|__/ /$$__ $$
| $$ \__/| $$ /$$ /$$$$$$/$$$$ | $$ \__/ /$$$$$$ /$$$$$$ /$$$$$$$
| $$$$$$ | $$| $$| $$_ $$_ $$| $$$$$$ /$$__ $$ /$$__ $$ /$$_____/
\____ $$| $$| $$| $$ \ $$ \ $$ \____ $$| $$ \ $$| $$$$$$$$| $$
/$$ \ $$| $$| $$| $$ | $$ | $$ /$$ \ $$| $$ | $$| $$_____/| $$
| $$$$$$/| $$| $$| $$ | $$ | $$| $$$$$$/| $$$$$$$/| $$$$$$$| $$$$$$$
\______/ |__/|__/|__/ |__/ |__/ \______/ | $$____/ \_______/ \_______/
| $$
| $$
|__/
SlimSpec : Towards Zero-Shot, API Spec Compression & Decompression
SlimSpec is a token-optimized format for representing API specifications with semantic precision. Designed for Zero-Shot LLM context window efficiency.
At the current iteration, It achieves 66% less tokens than traditional RAML.
Evaluations
3 Tests were done based on 3 examples: 1 - Simple CRUD API 2 - Complex E-commerce API 3 - Nested and recursive structures
Compression Test compression All popular LLMs appear to be able to compress SlimSpec to a similar token count.
Decompression Test decompression Sonnet > Gemini > Gpt-4o > Deepseek.
Rubric was tested with Zero-Shot decompression with NO CONTEXT WHATSOEVER.
Features
- 60-70% token reduction compared to standard API specifications
- Complete semantic preservation for lossless conversion
- Support for complex type systems, inheritance, and validation rules
- Preserves exact structure of request/response bodies
- Maintains precision for date/time types, formats, and constraints
Installation
# Install globally
bun install -g slimspec
# Or run with bunx
bunx slimspec
Usage
# Compress all files in current directory
slimspec c .
# Compress specific file
slimspec c ./api-spec.raml
# Compress with specific model
slimspec c . --model openai:gpt-4o
# Compress with custom prompt
slimspec c . --prompt ./custom-prompt.txt
# Compress to custom output directory
slimspec c . --output ./compressed-specs
# Decompress all .apaic files in current directory
slimspec d .
# Decompress specific file
slimspec d ./api-spec.apaic
# Decompress with specific model
slimspec d . --model openai:gpt-4o
# Decompress with custom prompt
slimspec d . --prompt ./custom-decompress-prompt.txt
# By default, fileps are saved in the same directory as the input file
# To save in a custom output directory:
slimspec d . --output ./decompressed-specs
Syntax Reference
Metadata
@meta{title:API Name,version:v1,baseUri:uri,mediaType:a/json}
Type Definitions
T:TypeName{field1:s!,field2:i?,nested:{prop:s!}}
T:Child:Parent{additionalField:s!}
Error Definitions
E:ErrorType{code:i!,message:s!,details:s?}
Traits & Security
@trait:pagination{limit:i?=20,offset:i?=0}
@security:oauth2{tokenUri:s!,scopes:s[]}
Endpoints
GET/resources|{@trait:pagination}|{200(a/json):*Resource[],404:*Error}
POST/resources|{field1:s!,field2:i?}@originalInline|{201:*Resource,400:{message:s!}}
PUT/resources/{id:s!}|{*Resource}|{200:*Resource,404}
PATCH/resources/{id}|{field1:s?}|{200:*Resource,404}
DELETE/resources/{id}||{204,404}
Type System
s
- stringi
- integern
- numberb
- booleand(date)
- date-onlyd(datetime)
- datetimetype[]
- arraye(val1|val2)
- enum!
- required?
- optional?=default
- optional with default
Formats & Constraints
s(uuid)
- UUID formats(email)
- Email formats(uri)
- URI formats(3,100)
- Min/max lengthi>=0
- Minimum values~regex
- Pattern matching
Example
RAML
types:
User:
properties:
id: string
email:
type: string
format: email
required: true
createdAt: datetime
/users:
get:
responses:
200:
body:
application/json:
type: array
items: User
SlimSpec
@meta{mediaType:application/json}
T:User{id:s?,email:s(email)!,createdAt:d(datetime)?}
GET/users||{200(a/json):*User[]}
License
MIT
0.0.1
4 months ago