Cloud Glossary Management

CLOUD

Centralized business glossary with terms, metrics, dimensions, and policies shared across teams and projects.

Overview

The Cloud Glossary provides:

• Centralized Terminology: Shared business terms across projects
• Metric Definitions: SQL definitions for calculated metrics
• Dimension Definitions: Categorization attributes
• Data Governance: Policies and rules enforcement
• Term Linking: Link terms to assets and columns

Creating Terms

Create a Term

Endpoint: POST /api/msh/glossary/terms

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": 1,
    "name": "Customer",
    "id": "term.customer",
    "description": "A customer is an individual or organization that purchases products or services",
    "synonyms": ["client", "buyer"],
    "owner": "data-team@company.com"
  }' \
  https://api.msh.io/api/msh/glossary/terms/

Response:

{
  "success": true,
  "term": {
    "id": 1,
    "name": "Customer",
    "id": "term.customer",
    "description": "...",
    "project": 1
  }
}

Creating Metrics

Create a Metric

Endpoint: POST /api/msh/glossary/metrics

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": 1,
    "name": "Monthly Recurring Revenue",
    "id": "metric.mrr",
    "description": "Total recurring revenue normalized to a monthly period",
    "sql_definition": "SELECT SUM(amount) FROM {{ ref('subscriptions') }} WHERE status = 'active'",
    "time_grain": "month",
    "source_assets": ["subscriptions"],
    "owner": "finance-team@company.com"
  }' \
  https://api.msh.io/api/msh/glossary/metrics/

Response:

{
  "success": true,
  "metric": {
    "id": 2,
    "name": "Monthly Recurring Revenue",
    "id": "metric.mrr",
    "sql_definition": "...",
    "project": 1
  }
}

Creating Dimensions

Create a Dimension

Endpoint: POST /api/msh/glossary/dimensions

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": 1,
    "name": "Region",
    "id": "dim.region",
    "description": "Geographic region",
    "values": ["North", "South", "East", "West"],
    "type": "categorical"
  }' \
  https://api.msh.io/api/msh/glossary/dimensions/

Creating Policies

Create a Policy

Endpoint: POST /api/msh/glossary/policies

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": 1,
    "name": "No PII in public assets",
    "rule": "PII columns cannot be in public schema",
    "pii_columns": ["email", "ssn", "phone"],
    "applies_to": ["public.*"],
    "enforcement": "strict"
  }' \
  https://api.msh.io/api/msh/glossary/policies/

Linking Terms

Link Term to Asset

Endpoint: POST /api/msh/glossary/links

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "term": 1,
    "asset": 5,
    "column": "customer_id",
    "role": "primary_key"
  }' \
  https://api.msh.io/api/msh/glossary/links/

Roles:

• primary_key - Primary key column
• foreign_key - Foreign key column
• attribute - Regular attribute column

Exporting Glossary

Export Full Glossary

Endpoint: GET /api/msh/glossary/projects/{project_id}/export

curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.msh.io/api/msh/glossary/projects/1/export

Response:

{
  "project": {
    "id": 1,
    "name": "Analytics"
  },
  "terms": [
    {
      "id": 1,
      "name": "Customer",
      "description": "...",
      "links": [...]
    }
  ],
  "metrics": [...],
  "dimensions": [...],
  "policies": [...]
}

API Endpoints Summary

Endpoint	Method	Description
/api/msh/glossary/terms	GET/POST	Term CRUD operations
/api/msh/glossary/metrics	GET/POST	Metric CRUD operations
/api/msh/glossary/dimensions	GET/POST	Dimension CRUD operations
/api/msh/glossary/policies	GET/POST	Policy CRUD operations
/api/msh/glossary/links	GET/POST	Link terms to assets/columns
/api/msh/glossary/projects/{id}/export	GET	Export full glossary

Best Practices

1. Consistent Naming: Use consistent term names across projects
2. Document Formulas: Include SQL definitions for metrics
3. Link Terms: Link terms to assets and columns for better context
4. Define Policies: Create policies for data governance
5. Regular Updates: Keep glossary updated as business evolves

Related Documentation

• Glossary Overview - OSS glossary features
• Managing Terms - OSS term management
• API Reference - Complete API documentation