Enum ReferenceMode 

pub enum ReferenceMode {
    Inline,
    Reference {
        prefix: String,
    },
}

Control whether nested DamlTyCon are referenced or inlined.

If Inline mode is set then the encoder will attempt to emit the target data type nested under the parent data type.

If Reference mode is set then the encoder will attempt to emit an absolute reference to a data type from a given prefix. In this mode it is assumed the the target data type will be emitted elsewhere and made available under the prefix.

It is not possible to emit every possible DamlTyCon in the requested mode and so there are some specific rules which apply based on the requested mode, whether the target data type is recursive and whether the target type expects type parameters.

• Recursive: Indicates that the DamlTyCon resolves to a data type which (directly or indirectly) contains itself as a field or type argument.

• Type Parameters: Indicates that the DamlTyCon resolves to a data type which has type one or more parameters that must be resolved before that data type can be emitted.

The following table enumerates how a DamlTyCon will be encoded for all possible cases:

Mode	Recursive?	Type params?	Encoding
Inline	No	No	1 - Encode target type inline
Inline	No	Yes	2 - Encode target type inline (with resolved type arguments)
Inline	Yes	No	3 - Encode to accept any object
Inline	Yes	Yes	4 - Encode to accept any object
Reference	No	No	5 - Encode as reference to target type
Reference	No	Yes	6 - Encode target type inline (fallback to #2)
Reference	Yes	No	7 - Encode as reference to target type
Reference	Yes	Yes	8 - Encode as accept any object (no fallback possible)

Cases 1, 2, 5 & 7 are straightforward, whereas cases 3, 4, 6 & 8 are more complex:

• Cases 3 & 4:

If Inline mode is chosen and the DamlTyCon resolves to a data type which is recursive then the emitter emits a JSON schema object which matches any JSON type:

For example, given:

data Rec = Rec with foo: Text, bar: Rec

The data type Rec includes itself recursively and so cannot be emitted Inline and will instead be emitted as follows:

{
   "description": "Any (Rec)",
   "comment": "inline recursive data types cannot be represented"
}

• Case 6:

If Reference mode is chosen and the DamlTyCon resolves to a data type which expects type parameters we do not emit a reference as the fully resolved target data type is unknown. In this case the emitter will fallback to Inline mode.

For example, given:

data Bottom a = Bottom with bottom: a
data Middle = Middle with middle: Bottom Int

Attempting to emit the middle: Bottom Int field in Reference mode (with a prefix of #/components/schemas/) cannot emit the below reference as this does not account for the type parameter applied to Bottom, of which there are infinitely many:

{
  "$ref": "#/components/schemas/Bottom"
}

Instead, the schema for Bottom Int will be emitted Inline.

• Case 8:

Case 8 is similar to case 6, however, the DamlTyCon resolves to a data type which is also recursive. In this case we cannot ‘fallback’ to Inline mode as recursive types cannot be inlined. The emitter therefore emits a JSON schema object which matches any JSON type.

For example, given:

data TopRec a = TopRec with top: TopRec a

The structure TopRec is both recursive and has a type parameter and therefore cannot be emitted as a $ref nor can it ‘fallback’ to Inline mode.

Variants

Inline

Inline nested DamlTyCon.

Reference

Reference nested DamlTyCon by $ref from prefix.

Fields

prefix: String

Trait Implementations

impl Clone for ReferenceMode

fn clone(&self) -> ReferenceMode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ReferenceMode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ReferenceMode

fn default() -> Self

Returns the “default value” for a type.