Save domain template

Saves changes to a domain's template. You can send the entire template or just the sections you want to update.

The template field accepts a JSON object or a YAML string. Set format to "yaml" when sending YAML; if omitted, the format is auto-detected (JSON is tried first, then YAML).

Partial updates (default): When preserveOmittedSections is true (the default), any top-level section you leave out of your request is automatically preserved from the current template. For example, you can update just datasets without losing your existing relationships or calculatedMetrics.

Full replacement: Set preserveOmittedSections to false to replace the entire template. Any section you omit will be cleared.

The response returns the normalized template as it was stored, so you can verify exactly what was saved. The server validates the template and returns any warnings (e.g., unused calculated fields).

Clearing the label or description: Send label: null or description: null in the template to explicitly clear these fields.

Authorization

BearerAuth

AuthorizationBearer <token>

A project-scoped access token. Generate one via the Token API with your projectId and projectSecret.

In: header

Path Parameters

domainId*string

The unique identifier of the semantic domain.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

template*|

The template definition as a JSON object, or as a YAML string when format is set to "yaml".

format?string

Tells the server how to parse template when it's a string. If omitted, the server tries JSON first, then YAML.

Value in"json" | "yaml"

preserveOmittedSections?boolean

Controls what happens to template sections you don't include in your request.

When true (the default), omitted sections are preserved from the currently saved template. This lets you update just one part of the template (e.g., datasets) without losing the rest (e.g., relationships, calculatedMetrics).

When false, the template you send fully replaces the stored template. Any section you omit will be cleared.

Defaulttrue

Response Body

`application/json`

curl -X put "https://semaphor.cloud/api/v1/domains/domain_abc123/template" \  -H "Content-Type: application/json" \  -d '{    "template": {      "id": "domain_abc123",      "datasets": [        {          "name": "orders",          "label": "Orders",          "type": "physical"        }      ]    },    "preserveOmittedSections": true  }'

{
  "save": {
    "success": true
  },
  "template": {
    "schemaVersion": "2.0",
    "id": "domain_abc123",
    "name": "sales_metrics",
    "label": "Sales Metrics",
    "description": "Revenue and order tracking",
    "datasets": [
      {
        "name": "orders",
        "label": "Orders",
        "type": "physical",
        "connectionId": "conn_1",
        "connectionType": "PostgreSQL",
        "catalog": "string",
        "schema": "public",
        "table": "orders",
        "sql": "string",
        "primaryKey": [
          "order_id"
        ],
        "fields": {
          "identifiers": [
            {}
          ],
          "dimensions": [
            {}
          ],
          "metrics": [
            {}
          ]
        }
      }
    ],
    "relationships": [
      {
        "id": "string",
        "name": "orders_to_customers",
        "sourceDataset": "orders",
        "sourceFields": [
          "customer_id"
        ],
        "targetDataset": "customers",
        "targetFields": [
          "id"
        ],
        "cardinality": "many_to_one",
        "defaultJoinType": "LEFT",
        "isAutoJoin": true,
        "joinPriority": 10,
        "discoveredBy": "ai",
        "confidence": "high",
        "isActive": true,
        "description": "string"
      }
    ],
    "calculatedMetrics": {},
    "calculatedDimensions": {},
    "grainMappings": [
      {}
    ]
  },
  "warnings": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ]
}

{
  "error": "string",
  "details": {},
  "errors": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ],
  "warnings": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ]
}

{
  "error": "string",
  "details": {},
  "errors": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ],
  "warnings": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ]
}

{
  "error": "string",
  "details": {},
  "errors": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ],
  "warnings": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ]
}

{
  "error": "string",
  "details": {},
  "errors": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ],
  "warnings": [
    {
      "code": "SCHEMA",
      "message": "Template schema error at datasets.0.name: Required",
      "severity": "error",
      "hint": "Update the domain template shape to match the semantic schema.",
      "context": {}
    }
  ]
}

Save domain template

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`