AWS SAM JSON Schema

[hoffa]

Introduction

We now provide a JSON Schema for AWS SAM templates (see #1133 for the original issue). It enhances the template authoring experience by enabling autocompletion, validation, and viewing documentation directly from your IDE. It supports all SAM and AWS CloudFormation resources.

Here's what it looks like in Visual Studio Code:

JSON Schema files

Warning
The schema is over 15 MB.
If you're integrating into other software, we highly recommend downloading the compressed schema instead. For example:

curl -H 'Accept-Encoding: gzip' https://raw.githubusercontent.com/aws/serverless-application-model/main/samtranslator/schema/schema.json | gunzip

• Latest stable AWS SAM JSON Schema
• Latest development AWS SAM JSON Schema

Autocompletion, validation, and documentation from your IDE

Using AWS Toolkit for Visual Studio Code

Install AWS Toolkit for Visual Studio Code and open any SAM template. It uses the SAM JSON Schema under the hood.

Note
There's a known performance issue with documentation tooltips in AWS Toolkit for Visual Studio Code. See aws/aws-toolkit-vscode#3259. If it's an issue, you can use the methods below as workaround.

Using the Visual Studio Code YAML extension

1. Install the YAML extension.

2. Paste the following at the top of your SAM template:

   # yaml-language-server: $schema=https://raw.githubusercontent.com/aws/serverless-application-model/main/samtranslator/schema/schema.json

Using Visual Studio Code JSON Schema support

If your template is in JSON format, add the following at the root of the template:

{
  "$schema": "https://raw.githubusercontent.com/aws/serverless-application-model/main/samtranslator/schema/schema.json"
}

Technical details

See here for more details.

Limitations

1. Limited support for intrinsic functions. Schema validation errors are expected when intrinsic functions are used. See SAM/CFN json schema: handle of intrinsic functions aws-toolkit-vscode#2596.
2. Only supports templates understood by the SAM transform. A template won't necessarily validate against the schema if it includes other AWS CloudFormation macros that modify the template. For example, the template in Fn::If intrinsic function inside Auth property of "AWS::Serverless::Api" #1859 (comment) doesn't pass schema validation since it uses AWS::LanguageExtensions to modify properties of a SAM resource.
3. Limited support for SAM pass-through values. Pass-through properties (e.g. AccessLogSettings) are passed directly to underlying CloudFormation resources. This is being addressed in feat: scaffolding for improved pass-throughs in schema #3055.

[CGarces]

I get some error on my SAM templates and the tooltip not provide information.
I'ts something wrong in my environment?

[hoffa]

Interesting. The error message isn't very helpful, but I'm guessing the sam.schema.json refers to https://github.com/awslabs/goformation/blob/master/schema/sam.schema.json (another SAM schema, not from the SAM team) which is used among other places in the AWS Toolkit (see here) and the JSON Schema Store (see here).

[hoffa]

Was able to reproduce after installing AWS Toolkit. Looks like the schema features it ships as well are somehow interfering. We'll look into this, thanks for the heads-up!

Edit: see aws/aws-toolkit-vscode#3012

[jpinkney-aws]

We've fixed this in the VSCode-YAML extension so when users do:

# yaml-language-server: $schema=https://raw.githubusercontent.com/aws/serverless-application-model/main/samtranslator/schema/schema.json

at the top of their file it should now pick up the newly create sam schema instead! You just need to ensure that you have VSCode-YAML 1.11 and above

[justinmk3]

it should also be possible to manually select the json schema from the vscode status bar, but it seems like that is not working. tracked in aws/aws-toolkit-vscode#3012

[SimonCMoore]

We are looking into a resolution but if you want a temporary workaround should you encounter the above issue, locate AWS Toolkit in your installed packages and you can temporarily disable, reload vscode and you can then use the schema as described.

[ryanotella]

IntelliJ

[HanaaGhasoub]

How can I reference to external file has the definition of the resources in SAM template with json format

[hoffa]

The JSON schema doesn't help with referencing external files, it only helps with the development experience of reading and writing valid templates by providing things like autocompletion and documentation.

To answer your question however, you should be able to include JSON files as such:

Fn::Transform:
  Name: AWS::Include
  Parameters:
    Location: <path-to-json>

For example:

Transform: AWS::Serverless-2016-10-31
Resources:
  Fn::Transform:
    Name: AWS::Include
    Parameters:
      Location: resources.json

Where resources.json is:

{
  "MyTable": {
    "Type": "AWS::Serverless::SimpleTable"
  }
}

You'll need to use the SAM CLI to deploy, so that it can package the assets for you.

If the issue is with the error in the IDE (but no issue with deployments), if you can specify what the error is and the parent keys of Resources (to understand where in the template it shows up), I can check in the schema and update if it's a type that should be valid (within the limitations mentioned in #2645 (comment)).

[HanaaGhasoub]

@hoffa Thank you so much, that's pretty explanation. I will follow your instructions and update you with result.