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 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:

  • firestore/default/data/services/:serviceId/projects/:projectId
  • firestore/otherdb/data/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

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.

Variant Entity Blueprint

Variant Entities 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.

Adapter Entity Blueprint

Adapter Entities are an advanced feature that help connect highly complex data structures. There are currently two Adapter types:

Nested List Adapter

Provides a named abstraction for deeply nested List types that allows them to be used within other containers (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)>, now you can use it inside another container type like a Map of Lists of Products: Map<String, Adapter(ProductsList)>.

Nested Map Adapter

Provides a named abstraction for deeply nested Map types that can be used within other 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)>. This would allow managing a Map of Maps of Products.

Note that in Dogen, Maps are different from Entities in that Maps have flexible keys (and values in some cases).

Type System (TypeSpec)

TypeSpec is Dogen's type system defining both the type and behavior of Blueprint fields. 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: // Generated via 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

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

Double Flavors

Double(@RatingFiveStars) : Firestore.Number

Five star rating input with validation

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 six powerful relationship types for each of your Object Entities. For example, when you create a Product entity using an Object Entity Blueprint, Dogen creates six ways to link back to Products from other entities:

Document Relationship

String(ProductFirestoreDocumentRelationship) : Firestore.String

Links to a specific product document. Stores the complete path to the document as a string, providing full context about its location in the database.

Document Relationship Denormalizer

String(ProductFirestoreDocumentRelationshipDenormalizer) : Firestore.String

Functions like a Document Relationship but with one-time data copying. When you select a target Product, this field takes a snapshot of the target and copies matching fields into the current document's fields. This creates a static copy of the data at selection time. Only fields with identical names and compatible types are copied. Note that future changes to the target document will not update this copied data automatically. If you need automatic updates, you can leverage Firestore functions.

Document Relationship ID

String(ProductFirestoreDocumentRelationshipId) : Firestore.String

Stores just the document ID without its path. This lightweight option saves only the unique identifier of the related document 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.

Collection Relationship

String(ProductFirestoreCollectionRelationship) : Firestore.String

Creates a reference to an entire collection of products. Stores the full path to the collection as a string.

Document Reference

Embedded(ProductFirestoreDocumentReference) : Firestore.Reference

Stores a native Firestore reference object pointing to a Product document. Use this when you need to perform Firestore operations directly on the reference.

Document Reference Denormalizer

Embedded(ProductFirestoreDocumentReferenceDenormalizer) : Firestore.Reference

Functions like a Document Reference but with one-time data duplication. When you select a target Product, this field stores the reference and takes a snapshot of the target document, copying matching fields into sibling fields in the current document. This provides a static copy of the data at selection time. Only fields with matching names and compatible types are copied. Important: future changes to the target document will not automatically update this copied data automatically. If you need automatic updates, you can leverage Firestore functions.

Entity Picker Interface

All relationship and reference fields give you access to Dogen's intuitive entity picker interface. This visual browser makes it easy to find and select related records while maintaining proper database paths.

Screenshot showing a relationship field.

Simply click on a placeholder or ID to open the entity picker and browse available connected documents.

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.