Understanding Artifact Definitions
Artifact definitions are JSON Schema-based contracts that define how infrastructure components can interact with each other in Massdriver. They serve as the foundation for connecting different infrastructure components and enabling seamless integration between them.
Overview
Artifact definitions serve several key purposes:
- Contract Definition: They define the contract between Infrastructure as Code (IaC) module executions/runs
- State Transit: They enable state to be passed between different IaC tools
- Platform Extension: They extend cloud support and UI capabilities of the platform
- Serialization: They define how artifacts can be downloaded and serialized
Structure
Every artifact definition must contain two top-level fields:
data
(object): Contains the encrypted data that will be stored at restspecs
(object): Contains UI integrations and display data
Example Structure
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "https://api.massdriver.cloud/artifact-definitions/ORG/NAME",
"type": "object",
"required": ["data", "specs"],
"properties": {
"data": {
"type": "object",
"properties": {
// Data properties here
}
},
"specs": {
"type": "object",
"properties": {
// Spec properties here
}
}
}
}
Identification
Artifact definitions are identified using the following pattern:
ORG_SLUG/ARTIFACT_DEFINITION_TYPE_NAME
For example: massdriver/aws-s3-bucket
The pattern follows this regex:
[a-z0-9-]+\/[a-z0-9-]+
Usage in massdriver.yaml
Artifact definitions are referenced in massdriver.yaml files under two main sections:
:artifacts
: Defines the artifacts that a bundle can produce:connections
: Defines the artifacts that a bundle can consume
An example massdriver.yaml
file for an RDS OpenTofu Module:
# The database will require a network artifact to put the database in.
connections:
required:
- vpc
properties:
vpc:
$ref: massdriver/aws-vpc
# The will emit an artifact with security group, db connection secrets, and iam policies
artifacts:
required:
- database
properties:
database:
$ref: massdriver/aws-rds-postgres
For more information about bundle configuration, see Bundle Configuration.
Artifact Lifecycle and Connection Phases
The lifecycle of artifact connections spans from initial package linking to final data injection. Through distinct phases of type validation and data exchange, artifact definitions ensure type safety and data integrity across your deployment pipeline.
Nominal Typing
When you connect two packages in the Massdriver UI, the system first checks if their artifact types are compatible—this is called nominal typing. Think of it like declaring variable types in programming: the system uses the artifact definition schemas to validate that the source and destination can be linked, even before any actual data is exchanged. Technically, when a downstream package is attached to an upstream package that hasn't yet emitted an artifact, the UI draws a dotted line to represent this "type-level" connection. The link is based solely on the artifact type definitions (the schema), similar to how class inheritance works in object-oriented programming—compatibility is determined by the type, not the data.
Structural Matching
Once the upstream package completes provisioning and emits its artifact data, the connection moves from type-level to data-level validation—this is structural matching. At this point, the system checks that the actual artifact data produced matches the expected schema. If it does, the link becomes "connected" (shown as a solid line in the UI), and the real artifact data (like connection strings, security groups, etc.) is injected into the downstream package during deployment. This ensures that not only are the types compatible, but the actual data structure and content are valid and ready for use in your deployment pipeline.
Linking Process
The connection lifecycle follows these steps:
- When two manifests are linked on the canvas, the system validates that the artifact types are compatible
- The connection is established when the source artifact's type matches the destination's expected type
- The system ensures no cyclical links are created
- Each destination field can only have one active link at a time
For more details about the linking process, see Manifest Linking.
Schema Location
All JSON schemas are hosted at:
https://api.massdriver.cloud/artifact-definitions/ORG/NAME
Usage
Artifact definitions are used to:
- Define the structure of infrastructure components
- Enable secure data transfer between components
- Provide UI integration points
- Define validation rules for connections
- Enable type checking between connected components
For examples of common artifact definition patterns, see Common Patterns.
Best Practices
- Always include both
data
andspecs
fields - Use clear, descriptive names for artifact types
- Follow the naming convention:
ORG_SLUG/ARTIFACT_DEFINITION_TYPE_NAME
- Include proper validation rules in the schema
- Document any special requirements or constraints
For a complete guide to creating artifact definitions, see Creating Artifact Definitions.