search

hashicorp / aws-cloudformation-resource-schema-sdk-go

This package provides AWS CloudFormation Resource Schema functionality in Go
Mozilla Public License 2.0
5 stars 2 forks source link

readme

aws-cloudformation-resource-schema-sdk-go

This package provides AWS CloudFormation Resource Schema functionality in Go, including the validation of schema documents, parsing of schema documents into native Go types, and offering methods for interacting with these schemas.

NOTE: There is a separate AWS CloudFormation resource specification, which is different than what is being described or handled in this package.

To browse the documentation before it is published on https://pkg.go.dev, you can browse it locally via godoc:

godoc -http=":6060" &
open "http://localhost:6060/pkg/github.com/hashicorp/aws-cloudformation-resource-schema-sdk-go"

Example Usage

Adding Go Module dependency to your project:

go get github.com/hashicorp/aws-cloudformation-resource-schema-sdk-go

Adding the import, using an import alias to simplify usage:

import {
  # ... other imports ...
  cfschema "github.com/hashicorp/aws-cloudformation-resource-schema-sdk-go"
}

Loading the meta-schema:

metaSchema, err := cfschema.NewMetaJsonSchemaPath("provider.definition.schema.v1.json")

Quickly validating a resource schema file path against the meta-schema:

err := metaSchema.ValidateResourcePath("aws-logs-loggroup.json")

Loading a resource schema for further processing:

resourceSchema, err := cfschema.NewResourceJsonSchemaPath("aws-logs-loggroup.json")

Validating a loaded resource schema against the meta-schema:

err := metaSchema.ValidateResourceJsonSchema(resourceSchema)

Validating a configuration against a loaded resource schema:

err := resourceSchema.ValidateConfigurationDocument("{...}")

Parsing the resource schema into Go:

resource, err := resourceSchema.Resource()

Expanding a resource schema to replace JSON Pointer references:

err := resource.Expand()

Further Reading

CloudFormation Resource Providers Schema

The specification for CloudFormation Resource Types is based on the CloudFormation Resource Providers Meta-Schema, which defines all the valid fields and structures for a resource schema. Additional information about creating these schemas files can be found in the Modeling resource types for use in AWS CloudFormation documentation.

Conceptually, the naming, typing, and some validation of attributes in the CloudFormation Schema are a flattened set of properties and re-usable definitions. Any nesting or re-usability is defined through JSON Pointer references. Additional concepts such as read-only, write-only, create-only attributes are implemented at the resource level and reference (potentially nested) attributes using JSON Pointers. The Initech::TPS::Report example resource schema can provide high level insight into the structure of these files.

JSON Pointers

CloudFormation Resource Providers Schemas make extensive use of JavaScript Object Notation (JSON) Pointers as described in RFC 6901.

JSON Schema

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. This is the specification on which CloudFormation Schemas are built. Understanding the core concepts and high level implementation details of this specification will provide a much clearer picture into the details of this Go package.

Some helpful resources for learning JSON Schema include: