com.digitalasset.transcode.schema

Compile-time representation of Schema. There are 4 main types of descriptors:

• '''Algebraic Data Types''': Record, Variant, Enumeration.
• '''Traversables''': List, Optional, TextMap, GenMap
• '''Primitive Types''': Unit, Bool, Text, Int64, Numeric, Timestamp, Date, Party, ContractId
• '''Type Constructors''' and Generic Types: Constructor, Application, Variable

Dictionary of templates, keys, choice arguments and choice results.

Dynamic types are represented by opaque types to reduce memory allocations during transformation from one codec to another.

There are 3 kinds of possible dynamic values:

• ADTs: records or variants. These are fixed in size, and are containers to other types. These types are addressable and have identifiers. There are special cases: enums and wrapped types.
• Traversables: lists, maps, optionals. These are variable in size and are containers to other types.
• Primitives: primitive scalar types.

Codecs and code-generations should be constructed in such a way that ADTs and Traversables expecting other underlying dynamic values in processing routines should know exactly what underlying values they expect. The unwrapping of dynamic value and casting should be safe then. SchemaProcessor takes care of constructing a tree of type processors and injects correct underlying processors where needed. See examples of how this is used in codecs: JSON and Grpc and code-gens: Java and Scala.

Tuple of Package ID, Module Name and Entity Name uniquely identify a template or a choice.

Tuple of Package Name, Module Name and Entity Name identify "equal in essence" entities, i.e. templates or choices that could be the results of upgrades of the same ancestor and therefore backward/forward compatible with each other This tuple will be used in equality checks of Maps, etc.

Package Version is a string that can be compared using SemVer rules

This trait describes various types that a Daml package can contain. SchemaProcessor will use an implementation of this trait to feed types into the visitor. The visitor implementation should define SchemaVisitor.Type, which can be a Codec, or a Code-generator along with instructions how to process daml types. There are several use cases:

==Codecs==

To achieve the best performance, a codec should create a tree-like structure copying the structure of Daml types with each node processing corresponding daml type and delegating processing to the next node if it's a type container.

A codec should convert to and from DynamicValue instances. This allows to compose codecs from various protocols by combining them in com.digitalasset.transcode.Converter. For example, one code combine JsonCodec and ProtobufCodec to get direct conversions from json to Ledger API proto values and vice versa. Or one can compose JsonCodec and ScalaCodec, etc.

Note, that Dynamic Values omit some type information (like field names or variant names) to reduce memory allocation and serialization. This information is known to the codec at the type of construction and codecs are encouraged to cache it.

==Code generators==

Code generators can produce code snippets at each handler and combine them into a file or a set of files that can be used as generated source in the target language.

It is advisable to also generate a codec along with DTOs (Data Transfer Object) to allow for direct interoperability with other existing protocols (Json or Protobuf).