domain-creation

Files (3)

• SKILL.md
• examples.md
• reference.md

SKILL.md (first lines)

## Prerequisites

Before creating domains, ensure you are on the correct workspace and branch. Use `get_session_workspace_and_branch` to check the current session context. For development work, create a branch with `create_workspace_branch` (the session switches automatically). See the `workspace-branch` skill for the full workspace/branch tool reference.

---

## Overview

A Honeydew **domain** is a lightweight governance object that defines a scoped business context over the semantic model.

Domains control:

- **Which entities** are visible (and optionally which fields within them via field selectors)
- **Semantic filters** (`filters`) — applied to every query in the domain, for governance and access control
- **Source filters** (`source_filters`) — applied early at the source level, for performance optimization

Domains are the primary mechanism for creating focused, governed views of the model for specific teams, use cases, or analysis contexts.

Domains can also **extend one or more parent domains** (`extends`), inheriting and building on their configuration. This lets you compose reusable base domains into specialized, team- or use-case-specific views. See [Domain Hierarchy](#domain-hierarchy) below.

> This skill focuses on domain creation and management.
> Use `entity-creation` to create entities and `attribute-creation` / `metric-creation` to add fields before scoping them into a domain.
> To expose a domain for AI analysis, create an agent referencing it using `create_agent` (MCP agent tools) or the Honeydew Studio agent builder.

---

## Creation Method

### create_object with YAML

Domains are created using `create_object` with domain YAML. There is no specialized `create_domain` tool.

Parameters:

- `yaml_text` — YAML defining the domain

Required permission: Editor or higher.

### Update: update_object

1. Use `search_model` (with `search_mode: EXACT`) to find the domain's `object_key`.
2. Call `update_object` with the full updated YAML (`yaml_text`) and the `object_key`.

> **Minimal diff rule:** When updating, preserve the existing field order and formatting from the current YAML. Only change the fields you need to modify.

### Delete: delete_object

1. Use `search_model` (with `search_mode: EXACT`) to find the domain's `object_key`.
2. Call `delete_object` with that `object_key`.

### After Creation/Update: Display the UI Link

After a successful `create_object` or `update_object` call, the response includes a `ui_url` field. **Always display this URL to the user** so they can quickly open the object in the Honeydew application.

---

## Decision Flow

```text
Need to create a domain?
    │
    ├─► Does an existing domain already define most of what you need?
    │       ├─► Yes, and you WANT to track it → extend it with `extends:` and override only
    │       │        the differences (see Domain Hierarchy). Note: extending creates a live
    │       │        dependency — future changes to the parent are automatically inherited by
    │       │        your domain. Extend when that shared evolution is desirable; define a
    │       │        standalone domain if you need to be insulated from the parent's changes.
    │       └─► No  → define a standalone domain (and consider whether it should become a reusable base)
    │
    ├─► Which entities should be included?
    │       └─► Use list_entities / search_model (OR mode) to discover available entities
    │
    ├─► Should all fields be visible, or only a subset?
    │       ├─► All fields → omit fields for that entity
    │       └─► Subset → use field selectors (supports wildcards and exclusions)
    │
    ├─► Are governance/access filters needed (apply to ALL queries)?
    │       └─► Use filters (semantic) with name + sql
    │
    └─► Are performance/source-level filters needed (apply only when entity is queried)?
            └─► Use source_filters with name + sql
```

---

## Domain Hierarchy

A domain can **extend one or more parent domains** using the `extends` field, inheriting their configuration and overriding only what differs. This is the recommended way to avoid duplicating entity selections, filters, and governance settings across related domains.

```yaml
type: domain
name: sales_us
extends:
  - base_sales        # inherit everything from base_sales
filters:
  - name: us_region   # add a child-specific filter
    sql: customers.country = 'US'
```

### What gets inherited

A child inherits from each parent: **entities** (and their field selections), **semantic and source filters**, **parameters**, **tags**, **labels** (additive), and all **metadata** sections.

### How items merge

List items are matched by `name` (tags by `key`, metadata sections by `name`):

- **Scalar fields** (e.g. a filter's `sql`) defined in the child **replace** the parent's value.
- **Collection fields** (e.g. an entity's `fields`) defined in the child **extend** the inherited list — child field selectors apply on top of the inherited field list.
- **Labels are additive** — child labels are appended to parent labels.
- To drop something inherited, add the item with `merge: remove` (works for entities, filters, source_filters, parameters, and tags).

### Multiple inheritance

List several parents under `extends`. Parents are evaluated **left-to-right**: if more than one parent defines the same item, the **rightmost parent wins**, and the child overrides all parents. This enables a mixin pattern — e.g. a base data model plus separate security and performance mixins composed into one domain.

### When to use a hierarchy

- When multiple domains share entities, fields, filters, or governance settings, factor the common configuration into a **base domain** and have the others extend it, rather than duplicating it.

From honeydew-ai/honeydew-ai-coding-agents-plugins, Apache-2.0.

More from honeydew-ai/honeydew-ai-coding-agents-plugins