Learn

Document with Metadata

⏱ 2 min read🟢 Beginner · 20-30 minutesTry in Learning Lab ↗Edit on GitHub ↗

Overview

Add metadata to your architecture to document ownership, versioning, and other important contextual information.

◎Learning objectives

By the end of this tutorial, you will:

• Understand metadata levels in CALM (architecture, node, relationship)
• Add metadata using both object and array formats
• Document ownership, versioning, and operational context
• Make your architectures discoverable and maintainable

✓Prerequisites

Complete Add Interfaces to Your Nodes first.

▶Try in Learning Lab

You can work through this tutorial in your browser with the CALM Learning Lab. There is nothing to install: the lab runs the real CALM engine, and the calm commands this tutorial uses work as they do in the CLI. The lab has no AI assistant, so you write the CALM yourself instead of prompting Copilot.

Open this tutorial in the Learning Lab ↗

Step-by-Step Guide

1. Understand CALM Metadata

Metadata in CALM can be added at three levels:

1. Architecture-level: Overall metadata for the entire system
2. Node-level: Metadata specific to individual components
3. Relationship-level: Metadata about connections

CALM supports two metadata formats:

Format 1: Object (Most Common)

{
  "metadata": {
    "owner": "[email protected]",
    "version": "1.0.0",
    "created": "2025-01-01",
    "environment": "production",
    "cost-center": "CC-12345",
    "tags": ["critical", "customer-facing"]
  }
}

Format 2: Array of Objects

{
  "metadata": [
    { "key": "owner", "value": "[email protected]" },
    { "key": "version", "value": "1.0.0" }
  ]
}

When to use which:

• Object format: Simpler, more readable, best for most cases
• Array format: When you need duplicate keys or want a more structured format

2. Add Architecture-Level Metadata

Open architectures/my-first-architecture.json in VSCode.

Prompt:

Update architectures/my-first-architecture.json to add top-level metadata.

The metadata should include:
- owner: your email or team name
- version: "1.0.0"
- created: today's date
- description: a brief description of what this architecture represents
- tags: an array of relevant tags (e.g., ["learning", "authentication", "demo"])

Use the object format for metadata.

Ensure the file still validates against CALM 1.2.

Review the output:

• ✅ metadata property added at the root level (same level as nodes and relationships)
• ✅ Contains owner, version, created, description, and tags
• ✅ Uses object format (not array)

Example result:

{
  "$schema": "https://calm.finos.org/release/1.2/meta/calm.json",
  "metadata": {
    "owner": "[email protected]",
    "version": "1.0.0",
    "created": "2025-01-15",
    "description": "Authentication system architecture for CALM learning",
    "tags": ["learning", "authentication", "microservices"],
    "status": "draft"
  },
  "nodes": [...],
  "relationships": [...]
}

3. Add Node-Level Metadata

Add metadata to your service node to document technical ownership.

Prompt:

Update the service node in architectures/my-first-architecture.json to add metadata.

The node metadata should include:
- tech-owner: the team that maintains this service
- repository: a placeholder URL to the code repository
- deployment-type: "container" or "serverless" or similar
- sla-tier: "tier-1", "tier-2", etc.

Use the object format for metadata.

Example result:

{
  "unique-id": "auth-service",
  "node-type": "service",
  "name": "Authentication Service",
  "description": "Handles user authentication",
  "interfaces": [...],
  "metadata": {
    "tech-owner": "[email protected]",
    "repository": "https://github.com/example/auth-service",
    "deployment-type": "container",
    "sla-tier": "tier-1",
    "programming-language": "Java"
  }
}

4. Add Relationship-Level Metadata

Add metadata to a relationship to document SLA or monitoring information.

Prompt:

Update the connects relationship in architectures/my-first-architecture.json to add metadata.

The relationship metadata should include:
- latency-sla: "< 100ms" or similar
- monitoring: true
- circuit-breaker: true or false

Use the object format for metadata.

Example result:

{
  "unique-id": "service-to-db",
  "description": "Service connects to database for user data",
  "relationship-type": {
    "connects": {...}
  },
  "metadata": {
    "latency-sla": "< 50ms",
    "monitoring": true,
    "circuit-breaker": true,
    "retry-policy": "exponential-backoff"
  }
}

5. Try the Array Format (Optional)

Experiment with the array format to understand the difference.

Prompt:

Show me how the metadata on my service node would look using the array format instead of the object format. Explain when I would choose one over the other.

6. Validate Your Architecture

calm validate -a architectures/my-first-architecture.json

◆Key concepts

Metadata Levels

Level	Scope	Example Properties
Architecture	Entire system	owner, version, environment
Node	Single component	tech-owner, repository, sla-tier
Relationship	Single connection	latency-sla, monitoring, circuit-breaker

Why Metadata Matters

Metadata transforms architecture files from anonymous diagrams into living documentation:

• Discoverability: Find who owns what
• Traceability: Track versions and changes
• Governance: Meet compliance requirements
• Operations: Know where to look when things break

Common Metadata Properties

Property	Purpose
owner	Who is responsible
version	Current version
created / modified	Timestamps
environment	dev/staging/prod
cost-center	Financial allocation
tags	Categorization
repository	Source code location
sla-tier	Service level

🔗Resources

• CALM Metadata Schema
• JSON Schema Documentation

💡Tips

• Use consistent metadata keys across your architectures
• Document metadata conventions in your team's guidelines
• Object format is usually easier to read and write
• Consider what questions stakeholders might ask about your architecture

→Next steps

In the next tutorial, you'll consolidate everything by building a complete e-commerce microservice architecture!