JSON Schema

Introduction

JSON Schemas (draft-07) for Serverless Framework v4 serverless.yml files and the AWS CloudFormation resources they compose. Editors such as the VS Code YAML extension and the IntelliJ family use these schemas to validate and auto-complete configuration.

There is no runtime — the artifacts are the schema files themselves.

List of schemas

• Serverless Framework Reference — official docs · raw link

Editor support

• VS Code — install the YAML extension and set yaml.schemaStore.enable: true.
• IntelliJ — all editors in the IntelliJ family auto-detect the schema via JSON Schema Store.

Repository layout

• serverless/reference.json — entry-point schema, bound to serverless.yml / serverless.yaml.
• serverless/components/ — hand-maintained shared definitions (CloudFormation intrinsic functions, IAM, Lambda, API Gateway v1/v2, ALB, events, conditions, outputs, parameters, mappings, etc.).
• serverless/plugins/ — schemas for supported Serverless Framework plugins (see Supported plugins below).
• serverless/resources/cloudformation/ — generated per-resource CFN schemas (~1100 files). Do not edit by hand; see Regenerating CFN schemas.
• serverless/resources/resources.schema.json — generated aggregate resource schema. Do not edit by hand.
• serverless/resources/third-party/ — git submodules for MongoDB Atlas and Datadog CloudFormation resources.
• test/ — YAML fixtures validated against reference.json by CI.

Getting started

Node version is pinned via .tool-versions (nodejs 26.0.0); pnpm version is pinned via packageManager in package.json.

git submodule update --init --recursive
pnpm install
pnpm test

pnpm test runs validate.mjs, which validates every fixture under test/ against serverless/reference.json and checks for dangling internal $refs. CI runs the same command on push and on PRs to master (.github/workflows/test.yml).

Regenerating CFN schemas

./cf-update.sh

This is the only build command. It:

1. Downloads the latest CloudFormation resource type schemas from AWS into serverless/resources/cloudformation/.
2. Updates the MongoDB Atlas and Datadog submodules.
3. Runs node index.js to transform the raw schemas in place and regenerate serverless/resources/resources.schema.json.

The transform is idempotent — strings already wrapped to accept CloudFormation intrinsic functions are detected and skipped, so re-running won't produce nested wrappers.

To run just the transformation step (no download): node index.js.

CFN resource fixes must go in index.js (transformation logic) or be filed upstream — direct edits to files in cloudformation/ are overwritten on the next run.

Supported plugins

• Serverless ESBuild
• Serverless Prune Plugin
• Serverless Python Requirements
• Serverless WSGI
• Serverless Split Stacks
• Serverless Step Functions
• Serverless SSM Publish
• Serverless Webpack

Contributing

Pull requests are welcome. See .github/pull_request_template.md for the expected checklist (change type, scope, references, test plan).

License

The MIT License (MIT). Please see License File for more information.