document

Documentation

Overview

Package document implements encoding and decoding of open-content that has a JSON-like data model. This data-model allows for UTF-8 strings, arbitrary precision numbers, booleans, nulls, a list of these values, and a map of UTF-8 strings to these values.

Interface defines the semantics for how a document type is marshalled and unmarshalled for requests and responses for the service. To send a document as input to the service you use NewLazyDocument and pass it the Go type to be sent to the service. NewLazyDocument returns a document Interface type that encodes the provided Go type during the request serialization step after you have invoked an API client operation that uses the document type.

The following examples show how you can create document types using basic Go types.

NewLazyDocument(map[string]interface{}{
    "favoriteNumber": 42,
    "fruits":         []string{"apple", "orange"},
    "capitals":       map[string]interface{}{
        "Washington": "Olympia",
        "Oregon":     "Salem",
    },
    "skyIsBlue":      true,
})

NewLazyDocument(3.14159)

NewLazyDocument([]interface{"One", 2, 3, 3.5, "four"})

NewLazyDocument(true)

Services can send document types as part of their API responses. To retrieve the content of a response document you use the UnmarshalSmithyDocument method on the response document. When calling UnmarshalSmithyDocument you pass a reference to the Go type that you want to unmarshal and map the response to.

For example, if you expect to receive key/value map from the service response:

var kv map[string]interface{}
if err := outputDocument.UnmarshalSmithyDocument(&kv); err != nil {
    // handle error
}

If a service can return one or more data-types in the response, you can use an empty interface and type switch to dynamically handle the response type.

var v interface{}
if err := outputDocument.UnmarshalSmithyDocument(&v); err != nil {
   // handle error
}

switch vv := v.(type) {
case map[string]interface{}:
    // handle key/value map
case []interface{}:
    // handle array of values
case bool:
    // handle boolean
case document.Number:
    // handle an arbitrary precision number
case string:
   // handle string
default:
   // handle unknown case
}

The mapping of Go types to document types is covered in more depth in https://pkg.go.dev/github.com/aws/smithy-go/document including more in depth examples that cover user-defined structure types.

Index

• type Interface
  • func NewLazyDocument(v interface{}) Interface

Types

type Interface

type Interface = internaldocument.Interface

Interface defines a document which is a protocol-agnostic type which supports a JSON-like data-model. You can use this type to send UTF-8 strings, arbitrary precision numbers, booleans, nulls, a list of these values, and a map of UTF-8 strings to these values.

You create a document type using the NewLazyDocument function and passing it the Go type to marshal. When receiving a document in an API response, you use the document's UnmarshalSmithyDocument function to decode the response to your desired Go type. Unless documented specifically generated structure types in client packages or client types packages are not supported at this time. Such types embed a noSmithyDocumentSerde and will cause an error to be returned when attempting to send an API request.

For more information see the accompanying package documentation and linked references.

func NewLazyDocument

func NewLazyDocument(v interface{}) Interface

You create document type using the NewLazyDocument function and passing it the Go type to be marshaled and sent to the service. The document marshaler supports semantics similar to the encoding/json Go standard library.

For more information see the accompanying package documentation and linked references.