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. |
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. |
Example:
name: CustomString
graphql:
typeName: CustomString
description: A custom string type
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. |
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. |
Example:
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
description: An author of a book
globalIdFields:
- author_id
graphql:
typeName: Author
dataConnectorTypeMapping:
- dataConnectorName: my_db
dataConnectorObjectType: author
fieldMapping:
author_id:
column:
name: id
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 | string | 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 |
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. |
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
ObjectBooleanExpressionType
Definition of a type representing a boolean expression on an Open DD object type.
| Key | Value | Required | Description |
|---|---|---|---|
kind | ObjectBooleanExpressionType | true | |
version | v1 | true | |
definition | ObjectBooleanExpressionTypeV1 | true | Definition of a type representing a boolean expression on an Open DD object type. |
ObjectBooleanExpressionTypeV1
Definition of a type representing a boolean expression on an Open DD object type.
| Key | Value | Required | Description |
|---|---|---|---|
name | CustomTypeName | true | The name to give this object boolean expression type, used to refer to it elsewhere in the metadata. Must be unique across all types defined in this subgraph. |
objectType | CustomTypeName | true | The name of the object type that this boolean expression applies to. |
dataConnectorName | DataConnectorName | true | The data connector this boolean expression type is based on. |
dataConnectorObjectType | string | true | The object type in the data connector's schema this boolean expression type is based on. |
comparableFields | [ComparableField] | true | The list of fields of the object type that can be used for comparison when evaluating this boolean expression. |
graphql | ObjectBooleanExpressionTypeGraphQlConfiguration / null | false | Configuration for how this object type should appear in the GraphQL schema. |
Example:
name: AuthorBoolExp
objectType: Author
dataConnectorName: my_db
dataConnectorObjectType: author
comparableFields:
- fieldName: article_id
operators:
enableAll: true
- fieldName: title
operators:
enableAll: true
- fieldName: author_id
operators:
enableAll: true
graphql:
typeName: Author_bool_exp
ObjectBooleanExpressionTypeGraphQlConfiguration
GraphQL configuration of an Open DD boolean expression type.
| Key | Value | Required | Description |
|---|---|---|---|
typeName | GraphQlTypeName | true | The name to use for the GraphQL type representation of this boolean expression type. |
GraphQlTypeName
The name to use for the GraphQL type representation of this boolean expression type.
Value: string
ComparableField
| Key | Value | Required | Description |
|---|---|---|---|
fieldName | FieldName | true | |
operators | EnableAllOrSpecific | true |
EnableAllOrSpecific
Must have exactly one of the following fields:
| Key | Value | Required | Description |
|---|---|---|---|
enableAll | boolean | false | |
enableSpecific | [string] | false |
FieldName
The name of a field in a user-defined object type.
Value: string
DataConnectorName
The name of a data connector.
Value: string
CustomTypeName
The name of a user-defined type.
Value: string