cfschema

package module
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2024 License: MPL-2.0 Imports: 10 Imported by: 3

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:

Documentation

Overview

aws-cloudformation-resource-schema-sdk-go handles CloudFormation Resource Providers Schema functionality in Go.

This includes, but is not limited to, wrapping JSON Schema library usage, validating resource schemas using the CloudFormation Resource Providers Meta-Schema, and providing native Go types/methods for working with a resource schema.

The README for this package has additional information about JSON Schema and CloudFormation Resource Providers.

Index

Constants

View Source 
const (
	HandlerTypeCreate = "create"
	HandlerTypeDelete = "delete"
	HandlerTypeList   = "list"
	HandlerTypeRead   = "read"
	HandlerTypeUpdate = "update"
)
View Source 
const (
	PropertyArrayTypeAttributeList = "AttributeList"
	PropertyArrayTypeStandard      = "Standard"
)
View Source 
const (
	PropertyFormatDate                = "date"
	PropertyFormatDateTime            = "date-time"
	PropertyFormatEmail               = "email"
	PropertyFormatHostname            = "hostname"
	PropertyFormatIdnEmail            = "idn-email"
	PropertyFormatIdnHostname         = "idn-hostname"
	PropertyFormatIpv4                = "ipv4"
	PropertyFormatIpv6                = "ipv6"
	PropertyFormatIri                 = "iri"
	PropertyFormatIriReference        = "iri-reference"
	PropertyFormatJsonPointer         = "json-pointer"
	PropertyFormatRegex               = "regex"
	PropertyFormatRelativeJsonPointer = "relative-json-pointer"
	PropertyFormatTime                = "time"
	PropertyFormatUri                 = "uri"
	PropertyFormatUriReference        = "uri-reference"
	PropertyFormatUriTemplate         = "uri-template"
)
View Source 
const (
	PropertyTypeArray   = "array"
	PropertyTypeBoolean = "boolean"
	PropertyTypeInteger = "integer"
	PropertyTypeNull    = "null"
	PropertyTypeNumber  = "number"
	PropertyTypeObject  = "object"
	PropertyTypeString  = "string"
)
View Source 
const (
	JsonPointerReferenceTokenSeparator  = "/"
	PropertiesJsonPointerReferenceToken = "properties"
	PropertiesJsonPointerPrefix         = JsonPointerReferenceTokenSeparator + PropertiesJsonPointerReferenceToken
)
View Source 
const (
	ReferenceAnchor          = "#"
	ReferenceSeparator       = "/"
	ReferenceTypeDefinitions = "definitions"
	ReferenceTypeProperties  = "properties"
)
View Source 
const (
	ReplacementStrategyCreateThenDelete = "create_then_delete"
	ReplacementStrategyDeleteThenCreate = "delete_then_create"
)

Variables

This section is empty.

Functions

func Sanitize added in v0.10.0 

func Sanitize(document string) (string, error)

Sanitize returns a sanitized copy of the specified JSON Schema document. The sanitized copy works around any problems with JSON Schema regex validation by

  • Rewriting all patternProperty regexes to the empty string (the regex is never used anyway)
  • Rewriting all unsupported (valid for ECMA-262 but not for Go) pattern regexes to the empty string

Types

type Handler 

type Handler struct {
	HandlerSchema    *HandlerSchema `json:"handlerSchema,omitempty"`
	Permissions      []string       `json:"permissions,omitempty"`
	TimeoutInMinutes int            `json:"timeoutInMinutes,omitempty"`
}

type HandlerSchema added in v0.21.0 

type HandlerSchema struct {
	AllOf      []*PropertySubschema `json:"allOf,omitempty"`
	AnyOf      []*PropertySubschema `json:"anyOf,omitempty"`
	OneOf      []*PropertySubschema `json:"oneOf,omitempty"`
	Properties map[string]*Property `json:"properties,omitempty"`
	Required   []string             `json:"required,omitempty"`
}

type MetaJsonSchema 

type MetaJsonSchema struct {
	// contains filtered or unexported fields
}

MetaJsonSchema represents the meta-schema for resource schemas

func NewMetaJsonSchemaDocument 

func NewMetaJsonSchemaDocument(document string) (*MetaJsonSchema, error)

NewMetaJsonSchemaDocument returns a MetaJsonSchema or any errors from the provided document.

func NewMetaJsonSchemaPath 

func NewMetaJsonSchemaPath(path string) (*MetaJsonSchema, error)

NewMetaJsonSchemaPath returns a MetaJsonSchema or any errors from the provided document at the file path.

func (*MetaJsonSchema) ValidateResourceDocument 

func (s *MetaJsonSchema) ValidateResourceDocument(document string) error

ValidateResourceDocument validates the provided document against the meta-schema.

func (*MetaJsonSchema) ValidateResourceJsonSchema 

func (s *MetaJsonSchema) ValidateResourceJsonSchema(resourceJsonSchema *ResourceJsonSchema) error

ValidateResourceJsonSchema validates the provided ResourceJsonSchema against the meta-schema.

func (*MetaJsonSchema) ValidateResourcePath 

func (s *MetaJsonSchema) ValidateResourcePath(path string) error

ValidateResourcePath validates the provided document at the file path against the meta-schema.

type Property 

type Property struct {
	AdditionalProperties *bool                    `json:"additionalProperties,omitempty"`
	AllOf                []*PropertySubschema     `json:"allOf,omitempty"`
	AnyOf                []*PropertySubschema     `json:"anyOf,omitempty"`
	ArrayType            *string                  `json:"arrayType,omitempty"`
	Comment              *string                  `json:"$comment,omitempty"`
	Default              interface{}              `json:"default,omitempty"`
	Description          *string                  `json:"description,omitempty"`
	Enum                 []interface{}            `json:"enum,omitempty"`
	Examples             []interface{}            `json:"examples,omitempty"`
	Format               *string                  `json:"format,omitempty"`
	InsertionOrder       *bool                    `json:"insertionOrder,omitempty"`
	Items                *Property                `json:"items,omitempty"`
	Maximum              *json.Number             `json:"maximum,omitempty"`
	MaxItems             *int                     `json:"maxItems,omitempty"`
	MaxLength            *int                     `json:"maxLength,omitempty"`
	Minimum              *json.Number             `json:"minimum,omitempty"`
	MinItems             *int                     `json:"minItems,omitempty"`
	MinLength            *int                     `json:"minLength,omitempty"`
	OneOf                []*PropertySubschema     `json:"oneOf,omitempty"`
	Pattern              *string                  `json:"pattern,omitempty"`
	PatternProperties    map[string]*Property     `json:"patternProperties,omitempty"`
	Properties           map[string]*Property     `json:"properties,omitempty"`
	Ref                  *Reference               `json:"$ref,omitempty"`
	RelationshipRef      *PropertyRelationshipRef `json:"relationshipRef,omitempty"`
	Required             []string                 `json:"required,omitempty"`
	Type                 *Type                    `json:"type,omitempty"`
	UniqueItems          *bool                    `json:"uniqueItems,omitempty"`
}

Property represents the CloudFormation Resource Schema customization for Definitions and Properties.

func (*Property) IsRequired added in v0.2.0 

func (p *Property) IsRequired(name string) bool

func (*Property) String 

func (p *Property) String() string

String returns a string representation of Property.

type PropertyJsonPointer 

type PropertyJsonPointer string

PropertyJsonPointer is a simplistic RFC 6901 handler for properties JSON Pointers.

func (*PropertyJsonPointer) EqualsPath 

func (p *PropertyJsonPointer) EqualsPath(other []string) bool

EqualsPath returns true if all path parts match.

This automatically handles stripping the /properties prefix.

func (*PropertyJsonPointer) EqualsStringPath 

func (p *PropertyJsonPointer) EqualsStringPath(path string) bool

EqualsStringPath returns true if the path string matches.

This automatically handles stripping the /properties prefix.

func (*PropertyJsonPointer) Path 

func (p *PropertyJsonPointer) Path() []string

Path returns the path parts.

This automatically handles stripping the /properties path part.

func (*PropertyJsonPointer) String 

func (p *PropertyJsonPointer) String() string

String returns a string representation of the PropertyJsonPointer.

type PropertyJsonPointers 

type PropertyJsonPointers []PropertyJsonPointer

PropertyJsonPointers is a list of PropertyJsonPointer.

func (PropertyJsonPointers) ContainsPath 

func (ptrs PropertyJsonPointers) ContainsPath(path []string) bool

ContainsPath returns true if an element matches the path.

type PropertyRelationshipRef added in v0.22.0 

type PropertyRelationshipRef struct {
	PropertyPath *PropertyJsonPointer `json:"propertyPath,omitempty"`
	TypeName     *string              `json:"typeName,omitempty"`
}

type PropertySubschema added in v0.8.0 

type PropertySubschema struct {
	AllOf      []*PropertySubschema `json:"allOf,omitempty"`
	AnyOf      []*PropertySubschema `json:"anyOf,omitempty"`
	OneOf      []*PropertySubschema `json:"oneOf,omitempty"`
	Properties map[string]*Property `json:"properties,omitempty"`
	Required   []string             `json:"required,omitempty"`
}

type PropertyTransform added in v0.17.0 

type PropertyTransform map[string]string

PropertyTransform represents property transform values.

func (PropertyTransform) Value added in v0.17.0 

func (p PropertyTransform) Value(path []string) (string, bool)

Value returns the value for a specified property path.

type Reference 

type Reference string

Reference is an internal implementation for RFC 6901 JSON Pointer values.

func (Reference) Field 

func (r Reference) Field() (string, error)

Field returns the JSON Pointer string path after the type.

func (Reference) String 

func (r Reference) String() string

String returns the string representation of a Reference.

func (Reference) Type 

func (r Reference) Type() (string, error)

Type returns the first path part of the JSON Pointer.

In CloudFormation Resources, this should be definitions or properties.

type Resource 

type Resource struct {
	AdditionalIdentifiers           []PropertyJsonPointers `json:"additionalIdentifiers,omitempty"`
	AdditionalProperties            *bool                  `json:"additionalProperties,omitempty"`
	AllOf                           []*PropertySubschema   `json:"allOf,omitempty"`
	AnyOf                           []*PropertySubschema   `json:"anyOf,omitempty"`
	ConditionalCreateOnlyProperties PropertyJsonPointers   `json:"conditionalCreateOnlyProperties,omitempty"`
	CreateOnlyProperties            PropertyJsonPointers   `json:"createOnlyProperties,omitempty"`
	Definitions                     map[string]*Property   `json:"definitions,omitempty"`
	DeprecatedProperties            PropertyJsonPointers   `json:"deprecatedProperties,omitempty"`
	Description                     *string                `json:"description,omitempty"`
	Handlers                        map[string]*Handler    `json:"handlers,omitempty"`
	NonPublicDefinitions            PropertyJsonPointers   `json:"nonPublicDefinitions,omitempty"`
	NonPublicProperties             PropertyJsonPointers   `json:"nonPublicProperties,omitempty"`
	OneOf                           []*PropertySubschema   `json:"oneOf,omitempty"`
	PrimaryIdentifier               PropertyJsonPointers   `json:"primaryIdentifier,omitempty"`
	Properties                      map[string]*Property   `json:"properties,omitempty"`
	PropertyTransform               PropertyTransform      `json:"propertyTransform,omitempty"`
	ReadOnlyProperties              PropertyJsonPointers   `json:"readOnlyProperties,omitempty"`
	ReplacementStrategy             *string                `json:"replacementStrategy,omitempty"`
	Required                        []string               `json:"required,omitempty"`
	ResourceLink                    *ResourceLink          `json:"resourceLink,omitempty"`
	SourceURL                       *string                `json:"sourceUrl,omitempty"`
	Taggable                        *bool                  `json:"taggable,omitempty"`
	Tagging                         *Tagging               `json:"tagging,omitempty"`
	TypeName                        *string                `json:"typeName,omitempty"`
	WriteOnlyProperties             PropertyJsonPointers   `json:"writeOnlyProperties,omitempty"`
}

func (*Resource) Expand 

func (r *Resource) Expand() error

Expand replaces all Definition and Property JSON Pointer references with their content. This functionality removes the need for recursive logic when accessing Definitions and Properties. In unresolved form nested properties are not allowed, instead nested properties use a '$ref' JSON Pointer to reference a definition. See https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-properties.

func (*Resource) IsCreateOnlyPropertyPath 

func (r *Resource) IsCreateOnlyPropertyPath(path string) bool

func (*Resource) IsRequired 

func (r *Resource) IsRequired(name string) bool

func (*Resource) ResolveProperties added in v0.6.0 

func (r *Resource) ResolveProperties(properties map[string]*Property) error

ResolveProperties resolves all References in a top-level name-to-property map. In theory unresolved form nested properties are not allowed but in practice they do occur, so support arbitrarily deeply nested references.

func (*Resource) ResolveProperty 

func (r *Resource) ResolveProperty(property *Property) (bool, error)

ResolveProperty resolves any Reference (JSON Pointer) in a Property. Returns whether a Reference was resolved.

func (*Resource) ResolveReference added in v0.6.0 

func (r *Resource) ResolveReference(ref Reference) (*Property, error)

ResolveReference resolves a Reference (JSON Pointer) into a Property.

func (*Resource) UnwrapOneOfProperties added in v0.14.0 

func (r *Resource) UnwrapOneOfProperties(property *Property) error

UnwrapOneOfProperties unwraps a set of properties nested in a oneOf element.

type ResourceJsonSchema 

type ResourceJsonSchema struct {
	// contains filtered or unexported fields
}

ResourceJsonSchema represents the resource schema.

func NewResourceJsonSchemaDocument 

func NewResourceJsonSchemaDocument(document string) (*ResourceJsonSchema, error)

NewResourceJsonSchemaDocument returns a ResourceJsonSchema or any errors from the provided document.

func NewResourceJsonSchemaPath 

func NewResourceJsonSchemaPath(path string) (*ResourceJsonSchema, error)

NewResourceJsonSchemaPath returns a ResourceJsonSchema or any errors from the provided document at the file path.

func (*ResourceJsonSchema) Resource 

func (s *ResourceJsonSchema) Resource() (*Resource, error)

Resource parses the JSON Schema and returns Resource or an error.

func (*ResourceJsonSchema) ValidateConfigurationDocument 

func (s *ResourceJsonSchema) ValidateConfigurationDocument(document string) error

ValidateConfigurationDocument validates the provided document against the resource schema.

func (*ResourceJsonSchema) ValidateConfigurationPath 

func (s *ResourceJsonSchema) ValidateConfigurationPath(path string) error

ValidateConfigurationPath validates the provided document at the file path against the resource schema. 

type ResourceLink struct {
	Comment     *string           `json:"$comment,omitempty"`
	Mappings    map[string]string `json:"mappings,omitempty"`
	TemplateURI *string           `json:"templateUri,omitempty"`
}

type Tagging added in v0.13.0 

type Tagging struct {
	Taggable                 *bool                `json:"taggable,omitempty"`
	TagOnCreate              *bool                `json:"tagOnCreate,omitempty"`
	TagUpdatable             *bool                `json:"tagUpdatable,omitempty"`
	CloudFormationSystemTags *bool                `json:"cloudFormationSystemTags,omitempty"`
	TagProperty              *PropertyJsonPointer `json:"tagProperty,omitempty"`
	Permissions              []string             `json:"permissions,omitempty"`
}

type Type 

type Type string

func (*Type) String 

func (t *Type) String() string

String is a string representation of Type.

func (*Type) UnmarshalJSON 

func (t *Type) UnmarshalJSON(b []byte) error

UnmarshalJSON is a custom JSON handler for Type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.