Configuration Reference

Complete reference for all yama.yaml configuration options.

Top-Level Structure


name: string          # Project name (required)
version: string       # API version (required)
 
database: object      # Database configuration
server: object        # Server settings
auth: object          # Authentication settings
schemas: object       # Schema definitions
endpoints: object     # API endpoints
plugins: array        # Plugin configuration

Project Info


name: my-api
version: 1.0.0
description: My Yama API

Field	Type	Required	Description
`name`	string	Yes	Project name
`version`	string	Yes	Semantic version
`description`	string	No	Project description

Database


database:
  url: ${DATABASE_URL}
  pool:
    min: 2
    max: 10
  ssl: true

Field	Type	Default	Description
`url`	string	-	Connection string (required)
`pool.min`	number	2	Minimum pool connections
`pool.max`	number	10	Maximum pool connections
`ssl`	boolean	false	Enable SSL connection

Server


server:
  port: ${PORT:-4000}
  host: 0.0.0.0
  cors:
    origin: "*"
    methods:
      - GET
      - POST
      - PUT
      - DELETE
    credentials: true
  logging:
    level: info
    format: json

Field	Type	Default	Description
`port`	number	4000	Server port
`host`	string	localhost	Server host
`cors.origin`	string/array	*	Allowed origins
`cors.methods`	array	all	Allowed HTTP methods
`cors.credentials`	boolean	false	Allow credentials
`logging.level`	string	info	Log level: debug, info, warn, error
`logging.format`	string	text	Log format: text, json

Authentication


auth:
  providers:
    - type: jwt
      secret: ${JWT_SECRET}
      expiresIn: 7d
      algorithm: HS256

JWT Provider

Field	Type	Default	Description
`type`	string	-	Provider type: `jwt`
`secret`	string	-	JWT secret key (required)
`expiresIn`	string	7d	Token expiration
`algorithm`	string	HS256	Signing algorithm

Schemas

Define data models using JSON Schema:


schemas:
  User:
    type: object
    required:
      - email
      - name
    properties:
      id:
        type: string
        format: uuid
      email:
        type: string
        format: email
      name:
        type: string
        minLength: 1
        maxLength: 100
      age:
        type: integer
        minimum: 0
      role:
        type: string
        enum:
          - user
          - admin
      createdAt:
        type: string
        format: date-time

Supported Types

Type	Description
`string`	Text values
`number`	Floating point numbers
`integer`	Whole numbers
`boolean`	true/false
`array`	Arrays
`object`	Nested objects

String Formats

Format	Description
`uuid`	UUID v4
`email`	Email address
`date`	ISO date (YYYY-MM-DD)
`date-time`	ISO datetime
`uri`	URL/URI
`password`	Password (masked in docs)

Validation Keywords

Keyword	Applies To	Description
`minLength`	string	Minimum length
`maxLength`	string	Maximum length
`pattern`	string	Regex pattern
`minimum`	number	Minimum value
`maximum`	number	Maximum value
`minItems`	array	Minimum items
`maxItems`	array	Maximum items
`enum`	any	Allowed values

References

Use $ref to reference other schemas:


schemas:
  Address:
    type: object
    properties:
      street:
        type: string
      city:
        type: string
 
  User:
    type: object
    properties:
      address:
        $ref: "#/schemas/Address"

Endpoints


endpoints:
  /users:
    get:
      handler: handlers/listUsers
      summary: List all users
      auth: required
      parameters:
        - name: limit
          in: query
          type: integer
          default: 10
      response:
        type: array
        items:
          $ref: "#/schemas/User"
    
    post:
      handler: handlers/createUser
      auth: required
      request:
        $ref: "#/schemas/CreateUserInput"
      response:
        $ref: "#/schemas/User"
 
  /users/{id}:
    get:
      handler: handlers/getUser
      response:
        $ref: "#/schemas/User"

Endpoint Options

Field	Type	Description
`handler`	string	Path to handler function (required)
`summary`	string	Brief description
`description`	string	Detailed description
`auth`	string/object	Authentication rule
`parameters`	array	Query/path parameters
`request`	object	Request body schema
`response`	object	Response schema
`tags`	array	OpenAPI tags

Auth Rules


# Public endpoint
auth: public
 
# Requires authentication
auth: required
 
# Optional authentication
auth: optional
 
# Role-based
auth:
  role: admin
 
# Multiple roles
auth:
  role:
    - admin
    - moderator

Parameters


parameters:
  - name: limit
    in: query
    type: integer
    default: 10
    description: Maximum results
  
  - name: id
    in: path
    type: string
    required: true

Field	Type	Description
`name`	string	Parameter name
`in`	string	Location: `query`, `path`, `header`
`type`	string	Data type
`required`	boolean	Is required
`default`	any	Default value
`description`	string	Description

Plugins


plugins:
  - name: "@betagors/yama-redis"
    config:
      url: ${REDIS_URL}
  
  - name: "@betagors/yama-s3"
    config:
      bucket: my-bucket
      region: us-east-1

Field	Type	Description
`name`	string	Plugin package name
`config`	object	Plugin-specific configuration

Environment Variables

Use ${VAR_NAME} syntax to reference environment variables:


database:
  url: ${DATABASE_URL}
 
server:
  port: ${PORT:-4000}  # With default value

Default Values


# ${VAR:-default} - Use default if VAR is unset or empty
port: ${PORT:-4000}
 
# ${VAR-default} - Use default only if VAR is unset
host: ${HOST-localhost}