Smithy Common Lisp

A Common Lisp code generator for Smithy protocol specifications that generates client libraries from Smithy JSON AST files. Primarily designed for generating AWS SDK clients.

Looking for an AWS SDK for Common Lisp? Check out pira - a ready-to-use AWS SDK generated by this library.

Overview

This library provides two main components:

1. Code Generator: Converts Smithy JSON AST files into Common Lisp code
2. Runtime SDK: Provides macros and infrastructure for defining SDK operations manually

The codegen system reads Smithy JSON specifications and generates complete Common Lisp client libraries with type definitions, operations, and protocol implementations.

Code Generation

Basic Usage

Generate Common Lisp code from Smithy JSON files:

(ql:quickload :smithy)

;; Generate from a single JSON file
(smithy:codegen-from-json #P"path/to/service.json"
                          :package-name "my-service"
                          :output #P"output/my-service.lisp")

;; Generate multiple AWS services
(smithy:codegen #P"path/to/aws-models/" #P"output/services/"
                :services '("s3" "ec2" "lambda")
                :prefix "aws/"
                :base-error-name 'aws-error)

Generated Code Structure

The generator creates:

• Type definitions using define-type, define-list, define-map, define-enum
• Structure definitions using define-structure, define-input, define-output, define-error
• Service definitions using define-service
• Operation definitions using define-operation

Example generated code for S3:

;; Type definitions
(smithy/sdk:define-type streaming-blob smithy/sdk:blob)
(smithy/sdk:define-list buckets :member (bucket :xml-name "Bucket"))

;; Input structure (minimal for list-buckets)
(smithy/sdk:define-input list-buckets-request ()
  ((max-buckets :target-type integer
                :member-name "MaxBuckets"
                :http-query "max-buckets"))
  (:shape-name "ListBucketsRequest"))

;; Output structure
(smithy/sdk:define-output list-buckets-output ()
  ((buckets :target-type buckets :member-name "Buckets")
   (owner :target-type owner :member-name "Owner"))
  (:shape-name "ListBucketsOutput"))

;; Operation definition
(smithy/sdk:define-operation list-buckets
  :shape-name "ListBuckets"
  :input list-buckets-request
  :output list-buckets-output
  :method "GET"
  :uri "/?x-id=ListBuckets")

;; More complex input with HTTP bindings
(smithy/sdk:define-input get-object-request ()
  ((bucket :target-type bucket-name
           :required t
           :member-name "Bucket"
           :http-label t)
   (key :target-type object-key
        :required t
        :member-name "Key"
        :http-label t)
   (if-match :target-type string
             :member-name "IfMatch"
             :http-header "If-Match"))
  (:shape-name "GetObjectRequest"))

;; Output with payload
(smithy/sdk:define-output get-object-output ()
  ((body :target-type streaming-blob
         :member-name "Body"
         :http-payload t)
   (content-type :target-type string
                 :member-name "ContentType"
                 :http-header "Content-Type"))
  (:shape-name "GetObjectOutput"))

;; Complete operation definition
(smithy/sdk:define-operation get-object
  :shape-name "GetObject"
  :input get-object-request
  :output get-object-output
  :method "GET"
  :uri "/{Bucket}/{Key+}?x-id=GetObject"
  :errors '(no-such-key))

Defining Services

(smithy/sdk:define-service s3
  :version "2006-03-01"
  :operations '(get-object put-object delete-object list-buckets)
  :traits
  '(("aws.api#service"
     ("arnNamespace" . "s3")
     ("endpointPrefix" . "s3"))
    ("aws.protocols#restXml"
     ("noErrorWrapping" . t))))

See Also

• Smithy Specification
• pira - Unofficial AWS SDK generated by smithy-lisp

License

MIT License - see LICENSE for details.