Blueprints

Blueprints are the foundation of your Dogen project. They define the structures of your data models. There are six main blueprint types, each with its own unique purpose and behavior. This section will guide you through each blueprint type and how to use them effectively.

Blueprint Types

Object Entity Blueprint

Object Entities represent your top-level collection documents in Firestore. They define the structure of your main data entities and can contain fields of any type.

Locations

Every Object Entity requires one or more locations. These are paths, supporting wildcard values, that tell Dogen where to find documents of this type. For example:

  • services/:serviceId/projects/:projectId
  • users/:userId/tasks/:taskId

Locations are crucial for both schema targetting and relationship pickers, as they help the system understand where to find and create entities of each type.

Screenshot showing an Object Entity Blueprint in the editor with location configuration

Embedded Entity Blueprint

Embedded Entities are reusable structures that can be nested within other entities. They're perfect for common field groupings that appear in multiple places in your data model.

Screenshot showing an Embedded Entity Blueprint in the editor

Adapter Entity Blueprint

Adapter Entities are a specialized type of Embedded Entity that helps conect data structures. There are currently two Adapter types:

Nested List Adapter

Provides a named abstraction for complex List types that can be used within container types (Lists or Maps). This makes nested container structures more manageable by giving them a clear, reusable name. For example, create a "ProductsList" adapter to represent List<Embedded(Product)>, then use it in a Map of Lists of Products: Map<String, Adapter(ProductsList)>.

Nested Map Adapter

Provides a named abstraction for complex Map types that can be used within container types (Lists or Maps). This makes nested container structures more manageable by giving them a clear, reusable name. For example, create a "ProductMap" adapter to represent Map<String, Embedded(Product)>, then use it in a nested Map as Map<String, Adapter(ProductMap)>.

Variant Entity Blueprint

Variant Entities are another type of Embedded Entity that allows a field to contain one of several different structured types (a union of multiple types).

Example: TransportationMode Variant

Could include types like:

  • Car (with fields for make, model, license plate)
  • Subway (with fields for line, station)
  • Bicycle (with fields for brand, gears)

When used in a field, the user can select which variant type they want and fill in the corresponding data structure.

Enum Entity Blueprint

Enum Entities define a fixed set of valid String values. Use them to create dropdown selections, status fields, or any other field that should only accept specific values.

Screenshot showing an Enum Entity Blueprint in the editor

Config Parameter Blueprint

Config Parameter Blueprints let you define configuration items and feature flags that can be easily managed through the configuration interface.

Use Config Parameters for specific values you wish to manage. You can then use these values to control the behavior of your application.
Avoid using Config Parameters for sensitive data like API keys or passwords since they are stored in plain text in Firestore.

Type System (TypeSpec)

TypeSpec is Dogen's type system that defines both the type and behavior of each Blueprint's field. Each TypeSpec requires a Dogen type, and optionally accepts an identifier in parentheses. The identifier can reference either an entity or a flavor, providing precise control over how fields are built in the generated client.

Dogen Types

The foundation of Dogen's type system includes these types:

Primitive Types: // Basic data types that form the building blocks of entities

Int, Double, Bool, String, DateTime

Custom Entity Types: // Can only be created from the corresponding Blueprint

Enum, // Set of predefined String values
Object, // Top-level document entities
Embedded, // Reusable nested structures
Adapter, // Connects data structures, allows abstracting nested Lists and Maps.
Variant, // Allows a field to be one of several different types (union) ↑ More details on Custom Entity Types

Container Types:

List<X>, Map<String, X> // X = Any Primitive or Custom Entity Type

TypeSpec is primarily a set of instructions that guide how Dogen generates your client interface. While it often mirrors your underlying data structure, it's not always a direct reflection of how it outputs data. For example, all relationship fields are defined as Embedded entities in TypeSpec but some output data as Strings and others as Firestore References.

Flavors

Flavors are like sub-types which are enhanced by specialized behaviors. Add them using the @ syntax, such as String(@Email) or Bool(@OptimisticBool).

String Flavors

String(@ColorARGB) : Firestore.String

Color picker with ARGB value storage

String(@Email) : Firestore.String

Email input with validation and proper keyboard type on mobile

String(@FirebaseStoragePathFile) : Firestore.String

File upload field with Firebase Storage default bucket integration

String(@FirebaseStoragePathImage) : Firestore.String

Image upload field with preview and Firebase Storage default bucket integration

String(@HiddenString) : Firestore.String

Hidden input field

String(@IPAddressV4) : Firestore.String

IPv4 address input with validation

String(@IPAddressV6) : Firestore.String

IPv6 address input with validation

String(@LongString) : Firestore.String

Multi-line text input for longer content

String(@Markdown) : Firestore.String

Rich text editor with markdown preview

String(@MaterialIcon) : Firestore.String

Material icon selector with preview

String(@Password) : Firestore.String

Secure password input field with mask

String(@URL) : Firestore.String

URL input with validation

String(@URLPath) : Firestore.String

URL path input with validation

String(@URLPathAbsolute) : Firestore.String

Absolute URL path requiring a leading slash with validation

String(@URLPathImage) : Firestore.String

Image URL path input without preview

String(@URLPathPDF) : Firestore.String

PDF URL path input with validation

Bool Flavors

Bool(@OptimisticBool) : Firestore.Boolean

Boolean flavor which defaults to true

DateTime Flavors

DateTime(@CreatedAt) : Firestore.TimeStamp

Automatically sets creation timestamp

DateTime(@UpdatedAt) : Firestore.TimeStamp

Automatically updates timestamp on changes

Embedded Entity Flavors

Embedded(@FirebaseAuthUserUpdatedBy) : Firestore.Map

Automatically outputs user info on updates

Output Map Fields:

{

uid : Firestore.String

displayName : Firestore.String

email : Firestore.String

}
Embedded(@FirebaseAuthUserCreatedBy) : Firestore.Map

Automatically outputs user info on creation

Output Map Fields:

{

uid : Firestore.String

displayName : Firestore.String

email : Firestore.String

}

Map Types

Map(@JSONObject) : Firestore.Map

Free form JSON Object

List Types

List(@JSONArray) : Firestore.Array

Free form JSON Array

Relationships & References

Available Relationship Types

Dogen automatically generates four different types of relationships for each of your Object Entities. For instance, if you create a Product entity using an Object Entity Blueprint, Dogen will generate four embeddable Product relationship types that you can use in other entities to establish connections:

Collection Relationship

Embedded(ProductFirestoreCollectionRelationship) : Firestore.String

Perfect for targeting collections of products. Outputs a string path to a collection.

Document Relationship

Embedded(ProductFirestoreDocumentRelationship) : Firestore.String

Ideal for pointing to specific product documents. Outputs a string path to a specific document.

Document Relationship ID

Embedded(ProductFirestoreDocumentRelationshipId) : Firestore.String

Represents a simple document ID. Outputs only the document ID as a string.

Consider using other relationship types when possible, as storing only IDs without location context can make document selection and path resolution more complex. However, if your use case specifically requires working with IDs, this type is still a valid option.

Document Reference

Embedded(ProductFirestoreDocumentReference) : Firestore.Reference

Outputs a Firestore reference pointing to a Product document.

We recommend using other relationship types when possible. Firestore References are mainly designed for Firebase's internal features and have limitations - for example, it doesn't support collection references, which reduces their flexibility.

Best Practices

For the best experience, use CollectionRelationship and DocumentRelationship. These provide:
  • Precise targeting with full path information
  • Use the same type and syntax for Collection and Document targetting.

Entity Picker Interface

When using all relationship or reference fields, you get access to Dogen's powerful entity picker interface. This makes it easy to browse, search, and select related records while maintaining proper path information.

Screenshot showing a relationship field.

Clicking on a placeholder or ID opens up the corresponding entity picker.

Screenshot showing the entity picker interface for relationships

Next Steps

Once you've completed the setup, you can:

Generate Your Client →

Ready to create your client? Learn about the generation process.

Configure Your Client →

Dive into the Configuration section to tweak your client's behavior and appearance.