Identifier Constraints Reference

This document describes the validation constraints and naming conventions for all identifier resources in Massdriver. These constraints are important for organizational design, naming standards, and deployment strategies.

Organization
Project
Environment (Target)
Manifest
Package
Bundle
Artifact Definition
Artifact
Bundle Deployment Metadata

Organization

Identifier Field: slug

Constraints

Pattern: ^[a-z0-9-]+$
- Lowercase letters, numbers, and hyphens only
- No underscores or other special characters
Length: Minimum 2 characters, maximum 64 characters
Uniqueness: Must be globally unique across all organizations

Examples

✅ Valid:

acme-corp
engineering-team
my-org-123

❌ Invalid:

AcmeCorp (uppercase letters)
my_org (underscores not allowed)
admin (reserved slug)
a (too short, minimum 2 characters)

Project

Identifier Field: slug

Projects are collections of manifests that compose an application or architecture. Project slugs are immutable once created.

Constraints

Pattern: ^[a-z][a-z0-9]{0,6}$
- Must start with a lowercase letter
- Can contain lowercase letters and numbers
- No hyphens or special characters
Length: Minimum 1 character, maximum 7 characters
Uniqueness: Unique within an organization
Immutability: Once created, the slug cannot be changed

Examples

✅ Valid:

webapp
api
data1

❌ Invalid:

web-app (hyphens not allowed)
WebApp (uppercase letters not allowed)
1webapp (must start with a letter)
verylongname (exceeds 7 character limit)

Environment (Target)

Identifier Field: slug

Environments represent named scopes for secrets and deployments within a project. Note: This resource was previously called "Target" and may occasionally be referenced that way for backwards compatibility - both terms refer to the same resource. Environment slugs are immutable once created.

Identifier Format: Environments use hierarchical slugs for API access. The full identifier format is {project-slug}-{environment-slug} (e.g., web-prod). You can use this hierarchical format in API calls, similar to how projects and packages are referenced.

Constraints

Pattern: ^[a-z][a-z0-9]{0,6}$
- Must start with a lowercase letter
- Can contain lowercase letters and numbers
- No hyphens or special characters
Length: Minimum 1 character, maximum 7 characters
Uniqueness: Unique within a project
Immutability: Once created, the slug cannot be changed

Examples

✅ Valid:

prod
staging
dev1

❌ Invalid:

prod-env (hyphens not allowed)
Prod (uppercase letters not allowed)
1dev (must start with a letter)
production (exceeds 7 character limit)

Manifest

Identifier Field: slug

A Manifest represents a bundle with a specific purpose or context within a project. For example, a Redis bundle might be added to a project multiple times, once for "caching" and once for "sessions" - each instance would be a separate manifest. Manifest slugs are immutable once created.

Constraints

Pattern: ^[a-z][a-z0-9]{0,11}$
- Must start with a lowercase letter
- Can contain lowercase letters and numbers
- No hyphens or special characters
Length: Minimum 1 character, maximum 12 characters
Uniqueness: Unique within a project
Immutability: Once created, the slug cannot be changed

Examples

✅ Valid:

redis
database
api-server

❌ Invalid:

redis-cluster (hyphens not allowed)
Redis (uppercase letters not allowed)
verylongmanifestname (exceeds 12 character limit)

Package

Identifier Field: slug (composite identifier)

A Package is a deployed instance of a manifest within a specific environment. It contains the configuration parameters and deployment state for that bundle in that environment.

Identifier Format: The package slug is a composite identifier: {project-slug}-{environment-slug}-{manifest-slug} (e.g., web-prod-api). Use this format as the package ID in API calls.

Constraints

Slug Format: {project-slug}-{environment-slug}-{manifest-slug}
- Example: web-prod-api
- Total length: 7 + 7 + 12 + 2 hyphens = 28 characters maximum
Uniqueness: Unique combination of environment and manifest within a project
API Access: Use the composite slug format (proj-env-manifest) as the package ID in API calls

Examples

✅ Valid Package:

Project slug: web
Environment slug: prod
Manifest slug: api
Package slug (ID): web-prod-api
API access: Use web-prod-api as the package ID

Name Prefix

The name_prefix is a read-only field that extends the package slug with a 4-character suffix: {project-slug}-{environment-slug}-{manifest-slug}-{suffix} (e.g., web-prod-api-abc1). Use name_prefix in your Infrastructure as Code (IaC) to name resources. The suffix is automatically generated and cannot be set directly.

Bundle

Identifier Field: name

Important Note: Bundle names are the OCI repository name. The full bundle identifier is the repository name plus a version tag (e.g., my-bundle:1.0.0). The full repository path is {organization-slug}/{bundle-name}.

Constraints

Pattern: ^[a-z][a-z0-9-]+[a-z0-9]$
- Must start with a lowercase letter
- Can contain lowercase letters, numbers, and hyphens
- Must end with a lowercase letter or number
- Cannot end with a hyphen
Length: Minimum 3 characters, maximum 53 characters
Uniqueness: Unique within an organization

Examples

✅ Valid:

redis-cluster
postgres-db
web-app-backend

❌ Invalid:

Redis-Cluster (uppercase letters)
redis- (cannot end with hyphen)
-redis (cannot start with hyphen)
re (too short, minimum 3 characters)

Artifact Definition

Identifier Field: name

Artifact definition names define the types of artifacts that can be created and managed. They follow an organization-scoped naming pattern.

Constraints

Pattern: [a-z0-9-]+\/[a-z0-9-]+
- Must contain a forward slash (/) separating two parts
- Format: organization-slug/artifact-type-name
- The artifact type name part (after the slash) must match: ^[a-z0-9-]{3,100}$
Length:
- Organization part: Follows organization slug constraints
- Artifact type name part: Minimum 3 characters, maximum 100 characters
Uniqueness: The artifact type name must be unique within your organization

Examples

✅ Valid:

acme-corp/vpc-network
my-org/custom-database
engineering/docker-registry

❌ Invalid:

vpc-network (missing slash)
acme-corp/VPC (uppercase in artifact type name)
acme-corp/vp (artifact type name too short, minimum 3 characters)

Artifact

Identifier Field: identifier

Artifacts have different identifier formats depending on whether they were provisioned through Massdriver or imported.

Constraints

For Provisioned Artifacts:

Format: {package.name_prefix}-{field}
Package name_prefix: {project-slug}-{environment-slug}-{manifest-slug}-{suffix}
Required Fields:
- name: Display name for the artifact
- field: Must be unique within a package, must match the field name defined in the bundle's artifact definition, cannot be changed after creation
- specs: Artifact specifications
- data: Artifact data

For Imported Artifacts:

Format: UUID
Required Fields:
- name: Display name for the artifact
- specs: Artifact specifications
- data: Artifact data

Examples

✅ Valid Provisioned Artifact:

Package name_prefix: web-prod-api-abc1
Field: database
Artifact identifier: web-prod-api-abc1-database

✅ Valid Imported Artifact:

Artifact identifier: 123e4567-e89b-12d3-a456-426614174000

Hierarchical Slug Identifiers

Many resources use hierarchical slug identifiers for API access:

Project: {project-slug} (e.g., web)
Environment: {project-slug}-{environment-slug} (e.g., web-prod)
Manifest: {manifest-slug} (scoped within project)
Package: {project-slug}-{environment-slug}-{manifest-slug} (e.g., web-prod-api)

Use these hierarchical identifiers to reference resources in API calls.

Summary Table

Resource	Identifier Field	Pattern	Min Length	Max Length	Scope	Notes
Organization	`slug`	`^[a-z0-9-]+$`	2	64	Global	Reserved slugs excluded
Bundle	`name`	`^[a-z][a-z0-9-]+[a-z0-9]$`	3	53	Organization	Must start/end with alphanumeric
Artifact Definition	`name`	`[a-z0-9-]+\/[a-z0-9-]+`	3	100	Organization	Format: `org/type-name`
Artifact	`identifier`	Computed	N/A	N/A	Organization	`{package.name_prefix}-{field}` for provisioned, UUID for imported
Project	`slug`	`^[a-z][a-z0-9]{0,6}$`	1	7	Organization	Immutable
Environment (Target)	`slug`	`^[a-z][a-z0-9]{0,6}$`	1	7	Project	Immutable, hierarchical ID: `proj-env`
Manifest	`slug`	`^[a-z][a-z0-9]{0,11}$`	1	12	Project	Immutable
Package	`slug`	`{proj}-{env}-{manifest}`	N/A	28	Project	Hierarchical slug used as ID, includes suffix in name_prefix

Bundle Deployment Metadata

When bundles are deployed, Massdriver automatically injects Bundle Deployment Metadata (md_metadata) into the deployment context. This metadata includes identifiers and context about the package, target environment, and deployment configuration.

The md_metadata object contains:

name_prefix: The package name prefix (incorporates project, target, and manifest slugs)
default_tags: Standard tags including md-project, md-target, md-manifest, and md-package identifiers
observability: Alarm webhook URL for the target
target: Target (legacy name for Environment) information including contact email
package: Package metadata with timestamps and status information

This metadata is available to all bundle deployments and can be used for resource naming, tagging, conditional logic, and observability integration.

Example md_metadata object structure:

{
  "name_prefix": "api-prod-database-1j39",                // Unique identifer for package
  "default_tags": {                                       // A default set of tags to include on your resources to integrate with Massdriver (Costs & Alerting)
    "managed-by": "massdriver",                           // Always set to "massdriver"
    "md-project": "my-project",                           // Project slug
    "md-target": "production",                            // Target (legacy name for Environment) slug. Target is legacy terminology.
    "md-manifest": "my-manifest",                         // Manifest slug
    "md-package": "my-package"                            // Package name prefix
  },
  "observability": {
    "alarm_webhook_url": "https://api.massdriver.cloud/targets/abc123/alarms?token=xyz"  // Webhook for alarm notifications
  },
  "target": {                                             // Target (legacy name for Environment) information
    "contact_email": "admin@example.com"                  // Organization owner email
  },
  "package": {                                            // Package metadata
    "created_at": "2024-01-15T10:30:00Z",                 // Package creation timestamp (ISO 8601)
    "updated_at": "2024-01-20T14:45:00Z",                 // Last update timestamp (ISO 8601)
    "deployment_enqueued_at": "2024-01-20T15:00:00Z",     // Current deployment enqueue time (ISO 8601)
    "previous_status": "provisioned"                          // Package status before this deployment
  }
}

For complete details on using md_metadata in your bundles, see Using Bundle Deployment Metadata.

Table of Contents​

Organization​

Constraints​

Examples​

Project​

Constraints​

Examples​

Environment (Target)​

Constraints​

Examples​

Manifest​

Constraints​

Examples​

Package​

Constraints​

Examples​

Name Prefix​

Bundle​

Constraints​

Examples​

Artifact Definition​

Constraints​

Examples​

Artifact​

Constraints​

Examples​

Hierarchical Slug Identifiers​

Summary Table​

Bundle Deployment Metadata​

Table of Contents

Organization

Constraints

Examples

Project

Constraints

Examples

Environment (Target)

Constraints

Examples

Manifest

Constraints

Examples

Package

Constraints

Examples

Name Prefix

Bundle

Constraints

Examples

Artifact Definition

Constraints

Examples

Artifact

Constraints

Examples

Hierarchical Slug Identifiers

Summary Table

Bundle Deployment Metadata