Types

Introduction

Types serve as the fundamental elements that define the structure of your data.

Being able to define types in your data domain is beneficial because it provides you with the flexibility to define them separately from the types referenced by a data connector's source.

The specification employs a concrete type system that includes both primitive and user-defined types. All subsequent layers, such as models, commands, and relationships are defined in terms of these types.

The types can be one of the following:

Type	Description
Primitive	These are the basic types ID, Int, Float, Boolean, or String.
Custom	These are user-defined types, such as ScalarType or ObjectType.
Type References	When specifying the types of a field or an argument, you can mark them as required ! or repeated [].

The spec also allows you to map existing data connector scalars to types in your data domain.

You can also define custom types by either aliasing existing types (such as primitives or custom), or you can define a type with fields. In turn, the fields themselves can be a primitive or another custom type.

Type references are types of fields and arguments that refer to other primitive or custom types and which can be marked as nullable, required or repeated (in the case of arrays).

Scalar type representation helps in mapping data connector scalars to any of the above types.

Primitive types and type references

Primitive types supported are ID, Int, Float, Boolean and String.

Type references follow GraphQL type syntax. Fields and arguments are nullable by default. To represent non-nullability, specify a ! after the type name. Similarly, array fields and arguments are wrapped in [].

Examples

If the field is nullable, it should be defined as

name: category
type: ProductCategory

If the field is non-nullable, it should be defined as

name: category
type: ProductCategory!

If the field is a nullable array of nullable type, it should be defined as

name: tags
type: [String]

If the field is a nullable array of non-nullable type, it should be defined as

name: tags
type: [String!]

If the field is a non-nullable array of nullable type, it should be defined as

name: tags
type:
  [String]!

If the field is a non-nullable array of non-nullable type, it should be defined as

name: tags
type:
  [String!]!

Metadata structure

ScalarType

Definition of a user-defined scalar type that that has opaque semantics.

Key	Value	Required	Description
kind	ScalarType	true
version	v1	true
definition	ScalarTypeV1	true	Definition of a user-defined scalar type that that has opaque semantics.

Example:

kind: ScalarType
version: v1
name: CustomString
graphql:
  typeName: CustomString
description: A custom string type

ScalarTypeV1

Definition of a user-defined scalar type that that has opaque semantics.

Key	Value	Required	Description
name	CustomTypeName	true	The name to give this scalar type, used to refer to it elsewhere in the metadata. Must be unique across all types defined in this subgraph.
graphql	ScalarTypeGraphQLConfiguration / null	false	Configuration for how this scalar type should appear in the GraphQL schema.
description	string / null	false	The description of this scalar. Gets added to the description of the scalar's definition in the graphql schema.

ScalarTypeGraphQLConfiguration

GraphQL configuration of an Open DD scalar type

Key	Value	Required	Description
typeName	GraphQlTypeName	true	The name of the GraphQl type to use for this scalar.

GraphQlTypeName

The name of the GraphQl type to use for this scalar.

Value: string

CustomTypeName

The name of a user-defined type.

Value: string

ObjectType

Definition of a user-defined Open DD object type.

Key	Value	Required	Description
kind	ObjectType	true
version	v1	true
definition	ObjectTypeV1	true	Definition of a user-defined Open DD object type.

Example:

kind: ObjectType
version: v1
definition:
  name: Author
  fields:
    - name: author_id
      type: Int!
      description: The id of the author
    - name: first_name
      type: String
      description: The first name of the author
    - name: last_name
      type: String
      description: The last name of the author
    - name: biography
      type: String
      description: AI generated biography for the author
      arguments:
        - name: ai_model
          argumentType: String!
          description: The AI model to use for generating the biography
  description: An author of a book
  globalIdFields:
    - author_id
  graphql:
    typeName: Author
  dataConnectorTypeMapping:
    - dataConnectorName: my_db
      dataConnectorObjectType: author
      fieldMapping:
        author_id:
          column:
            name: id
    - dataConnectorName: my_vector_db
      dataConnectorObjectType: author
      fieldMapping:
        biography:
          column:
            name: biography
            argumentMapping:
              ai_model: model

ObjectTypeV1

Definition of a user-defined Open DD object type.

Key	Value	Required	Description
name	CustomTypeName	true	The name to give this object type, used to refer to it elsewhere in the metadata. Must be unique across all types defined in this subgraph.
fields	[ObjectFieldDefinition]	true	The list of fields defined for this object type.
globalIdFields	[FieldName] / null	false	The subset of fields that uniquely identify this object in the domain. Setting this property will automatically implement the GraphQL Relay Node interface for this object type and add an id global ID field. If setting this property, there must not be a field named id already present.
graphql	ObjectTypeGraphQLConfiguration / null	false	Configuration for how this object type should appear in the GraphQL schema.
description	string / null	false	The description of the object. Gets added to the description of the object's definition in the graphql schema.
dataConnectorTypeMapping	[DataConnectorTypeMapping]	false	Mapping of this object type to corresponding object types in various data connectors.

DataConnectorTypeMapping

This defines the mapping of the fields of an object type to the corresponding columns of an object type in a data connector.

Key	Value	Required	Description
dataConnectorName	DataConnectorName	true
dataConnectorObjectType	DataConnectorObjectType	true
fieldMapping	FieldMappings	false

FieldMappings

Mapping of object fields to their source columns in the data connector.

Key	Value	Required	Description
<customKey>	FieldMapping	false

FieldMapping

Source field directly maps to some column in the data connector.

Key	Value	Required	Description
column	ColumnFieldMapping	true	The target column in a data connector object that a source field maps to.

ColumnFieldMapping

The target column in a data connector object that a source field maps to.

Key	Value	Required	Description
name	string	true	The name of the target column
argumentMapping	ArgumentMapping / null	false	Arguments to the column field

ArgumentMapping

Mapping of a comand or model argument name to the corresponding argument name used in the data connector. The key of this object is the argument name used in the command or model and the value is the argument name used in the data connector.

Key	Value	Required	Description
<customKey>	DataConnectorArgumentName	false

DataConnectorArgumentName

Value: string

DataConnectorObjectType

The name of an object type in a data connector.

Value: string

DataConnectorName

The name of a data connector.

Value: string

ObjectTypeGraphQLConfiguration

GraphQL configuration of an Open DD object type.

Key	Value	Required	Description
typeName	GraphQlTypeName / null	false	The name to use for the GraphQL type representation of this object type when used in an output context.
inputTypeName	GraphQlTypeName / null	false	The name to use for the GraphQL type representation of this object type when used in an input context.
apolloFederation	ObjectApolloFederationConfig / null	false	Configuration for exposing apollo federation related types and directives.

ObjectApolloFederationConfig

Key	Value	Required	Description
keys	[ApolloFederationObjectKey]	true

ApolloFederationObjectKey

Key	Value	Required	Description
fields	[FieldName]	true

GraphQlTypeName

Value: string

ObjectFieldDefinition

The definition of a field in a user-defined object type.

Key	Value	Required	Description
name	FieldName	true	The name of the field. This name is used both when referring to the field elsewhere in the metadata and when creating the corresponding GraphQl type.
type	TypeReference	true	The type of this field. This uses the GraphQL syntax to represent field types and must refer to one of the inbuilt OpenDd types or another user-defined type.
description	string / null	false	The description of this field. Gets added to the description of the field's definition in the graphql schema.
deprecated	Deprecated / null	false	Whether this field is deprecated. If set, the deprecation status is added to the field's graphql schema.
arguments	[FieldArgumentDefinition]	false	The arguments for the field

FieldArgumentDefinition

Key	Value	Required	Description
name	ArgumentName	true
argumentType	TypeReference	true
description	string / null	false

ArgumentName

Value: string

Deprecated

OpenDd configuration to indicate whether an object type field, relationship, model root field or command root field is deprecated.

Key	Value	Required	Description
reason	string / null	false	The reason for deprecation.

TypeReference

A reference to an Open DD type including nullable values and arrays. Suffix '!' to indicate a non-nullable reference, and wrap in '[]' to indicate an array. Eg: '[String!]!' is a non-nullable array of non-nullable strings.

Value: string

FieldName

The name of a field in a user-defined object type.

Value: string

CustomTypeName

The name of a user-defined type.

Value: string