Semantic Model JSON specification

This page documents the JSON structure of a semantic model and its versions, as created and edited through the Semantic Model editor described in Create, import and manage Semantic Models. It is a reference for the full field-level structure, useful when reasoning about a version’s content beyond what the editor UI surfaces directly.

Global structure

A semantic model is a container for one or more versions, one of which is designated as active.

Most of a semantic model’s content – entities, relationships, golden queries, glossary, and settings – lives inside a version, not at the top level.

Field	Type	Required	Description
id	string	Yes	Unique identifier of the semantic model
projectKey	string	Yes	Key of the project the semantic model belongs to
name	string	Yes	Name of the semantic model
description	string	No	Description of the semantic model
shortDesc	string	No	Short description of the semantic model
activeVersionId	string	No	id of the version currently used to answer queries
versions	array	No	The semantic model’s versions – see Versions
tags, customFields, checklists, versionTag, creationTag	–	No	Standard Dataiku object metadata, common to other DSS objects

Example:

{
  "id": "sm_id_1",
  "projectKey": "SALES_ANALYTICS",
  "name": "Sales Semantic Model",
  "description": "Sales analytics semantic layer",
  "shortDesc": "Sales semantic layer",
  "activeVersionId": "v1",
  "tags": [],
  "customFields": {},
  "checklists": {},
  "versionTag": {},
  "creationTag": {},
  "versions": []
}

Creation and modification tags

Metrics, filters, golden queries, glossary terms and glossary bindings each carry a created field (glossary terms also carry modified), recording when and by whom they were added or last changed.

Field	Type	Required	Description
on	string	No	Timestamp of the change
by	string	No	User who made the change
version	integer	No	Version number at the time of the change

Example:

{
  "on": "2026-05-27T12:00:00Z",
  "by": "[email protected]"
}

Versions

A version holds the full definition of a semantic model at a point in time: its entities, their relationships, and the settings used to generate SQL from natural language questions.

Field	Type	Required	Description
id	string	Yes	Unique identifier of the version
description	string	No	Description of the version
created	object	No	See Creation and modification tags
entities	array	No	The version’s entities – see Entities
relationships	array	No	Joins between entities – see Relationships
goldenQueries	array	No	See Golden queries
crossEntityMetrics	array	No	See Cross-entity metrics
glossaryTerms	array	No	See Glossary
glossaryBindings	array	No	See Glossary
indexingSettings	object	No	See Indexing settings
sqlGenerationConfig	object	No	See SQL generation config
privateEditorData	object	No	See Private editor data

Example:

{
  "id": "v1",
  "description": "Initial version",
  "created": {
    "on": "2026-05-27T12:00:00Z",
    "by": "[email protected]"
  },
  "entities": [],
  "relationships": [],
  "goldenQueries": [],
  "crossEntityMetrics": [],
  "glossaryTerms": [],
  "glossaryBindings": [],
  "indexingSettings": {},
  "sqlGenerationConfig": {},
  "privateEditorData": {}
}

Entities

An entity maps to a dataset in the project. It groups the attributes, metrics and filters built on top of that dataset.

Field	Type	Required	Description
name	string	Yes	Name of the entity
description	string	No	Description of the entity
tags	array of strings	No	Tags for the entity
type	string	No	Entity source type; currently always DATASET
datasetRef	string	No	The underlying dataset: its name for a dataset in the same project, or PROJECT_KEY.DATASET_NAME for a dataset in another project
attributes	array	No	See Attributes
metrics	array	No	Entity-level metrics – see Metrics
filters	array	No	See Filters
primaryKey	object	No	See Primary and foreign keys
foreignKeys	array	No	See Primary and foreign keys

Example:

{
  "name": "orders",
  "description": "Customer orders with revenue and status fields",
  "tags": [],
  "type": "DATASET",
  "datasetRef": "SALES_ANALYTICS.orders",
  "attributes": [],
  "metrics": [],
  "filters": [],
  "primaryKey": {
    "attributes": ["order_id"]
  },
  "foreignKeys": []
}

Attributes

Attributes map to columns of the entity’s dataset, or to expressions computed from them.

Field	Type	Required	Description
name	string	Yes	Name of the attribute
description	string	No	Description of the attribute
dssType	string	No	DSS type of the underlying column or expression (e.g. string, date, bigint)
type	string	No	COLUMN or EXPRESSION; defaults to COLUMN
column	string	No	Source column name, for type: COLUMN
pseudoSQLExpression	string	No	SQL expression, for type: EXPRESSION
distinctValuesHandlingMode	string	No	NONE, MANUAL or AUTO_INDEX; defaults to NONE. See below.
manualValues	array of strings	No	Sample values, used when distinctValuesHandlingMode is MANUAL
indexDistinctValues	boolean	No	Whether to index distinct values
resolveInUserRequests	boolean	No	Whether the attribute is resolvable: included in term resolution to fuzzy-match user query terms
llmInstructions	string	No	LLM instructions for this attribute
sqlGenerationConfig	object	No	Attribute-level SQL generation config. Supports autoValuesLimit (integer), the maximum number of distinct values fetched when distinctValuesHandlingMode is AUTO_INDEX.

distinctValuesHandlingMode determines where an attribute’s sample values come from: NONE tracks none, MANUAL uses the values listed in manualValues, and AUTO_INDEX fetches them automatically during indexing (see Create, import and manage Semantic Models).

Examples:

A COLUMN attribute with manually entered sample values:

{
  "name": "order_status",
  "description": "Current lifecycle status of the order",
  "dssType": "string",
  "type": "COLUMN",
  "column": "status",
  "distinctValuesHandlingMode": "MANUAL",
  "manualValues": ["pending", "shipped", "cancelled"],
  "indexDistinctValues": true,
  "resolveInUserRequests": true,
  "llmInstructions": "Use for order status questions.",
  "sqlGenerationConfig": {}
}

An EXPRESSION attribute, not resolvable:

{
  "name": "order_month",
  "description": "Calendar month of the order date",
  "dssType": "date",
  "type": "EXPRESSION",
  "pseudoSQLExpression": "DATE_TRUNC('month', order_date)",
  "distinctValuesHandlingMode": "NONE",
  "manualValues": [],
  "indexDistinctValues": false,
  "resolveInUserRequests": false,
  "sqlGenerationConfig": {}
}

A COLUMN attribute with automatically indexed sample values:

{
  "name": "region",
  "description": "Sales region of the order",
  "dssType": "string",
  "type": "COLUMN",
  "column": "region",
  "distinctValuesHandlingMode": "AUTO_INDEX",
  "manualValues": [],
  "indexDistinctValues": true,
  "resolveInUserRequests": true,
  "sqlGenerationConfig": {
    "autoValuesLimit": 100
  }
}

Metrics

Entity-level metrics are aggregations of the entity’s attributes.

Field	Type	Required	Description
name	string	Yes	Name of the metric
description	string	No	Description of the metric
pseudoSQLExpression	string	Yes	Aggregation expression (e.g. SUM(amount))
llmInstructions	string	No	LLM instructions for this metric
created	object	No	See Creation and modification tags

Example:

{
  "name": "total_revenue",
  "description": "Total revenue from all orders",
  "pseudoSQLExpression": "SUM(order_amount)",
  "llmInstructions": "Use when the user asks for sales or revenue totals.",
  "created": {
    "on": "2026-05-27T12:15:00Z",
    "by": "[email protected]"
  }
}

Filters

Filters are named, reusable WHERE clause fragments defined on an entity.

Field	Type	Required	Description
name	string	Yes	Name of the filter
description	string	No	Description of the filter
pseudoSQLExpression	string	Yes	WHERE clause fragment (e.g. status = 'shipped')
llmInstructions	string	No	LLM instructions for this filter
created	object	No	See Creation and modification tags

Example:

{
  "name": "completed_orders",
  "description": "Orders that have been shipped to customers",
  "pseudoSQLExpression": "status = 'shipped'",
  "llmInstructions": "Apply for completed or fulfilled orders.",
  "created": {
    "on": "2026-05-27T12:20:00Z",
    "by": "[email protected]"
  }
}

Primary and foreign keys

primaryKey lists the attribute(s) that uniquely identify a row of the entity. foreignKeys lists other entities this entity’s attributes point to; joins actually used for SQL generation are expressed at the version level, in Relationships.

Field	Type	Required	Description
primaryKey.attributes	array of strings	No	Names of the attributes making up the primary key
foreignKeys[].referencedEntity	string	Yes	Name of the referenced entity
foreignKeys[].key.attributes	array of strings	No	Names of the attributes making up the key

Example:

{
  "primaryKey": {
    "attributes": ["order_id"]
  },
  "foreignKeys": [
    {
      "referencedEntity": "customers",
      "key": {
        "attributes": ["customer_id"]
      }
    }
  ]
}

Relationships

Relationships are the version-level joins between two entities, described in Create, import and manage Semantic Models.

Field	Type	Required	Description
name	string	No	Name of the relationship
description	string	No	Description of the relationship
firstEntity	string	Yes	Name of the first entity
secondEntity	string	Yes	Name of the second entity
pseudoSQLExpression	string	No	Join hint (e.g. orders.customer_id = customers.customer_id)

Example:

{
  "name": "orders_to_customers",
  "description": "Each order belongs to one customer",
  "firstEntity": "orders",
  "secondEntity": "customers",
  "pseudoSQLExpression": "orders.customer_id = customers.customer_id"
}

Golden queries

Golden queries are pre-recorded questions and their expected SQL, described in Create, import and manage Semantic Models.

Field	Type	Required	Description
name	string	Yes	Name of the golden query
description	string	No	Description of the golden query
question	string	Yes	Natural language question
generatedSql	string	Yes	Expected SQL query
created	object	No	See Creation and modification tags

Example:

{
  "name": "monthly_revenue_emea",
  "description": "Monthly EMEA revenue for the last 6 months",
  "question": "What was monthly revenue in EMEA for the last 6 months?",
  "generatedSql": "SELECT DATE_TRUNC('month', order_date) AS month, SUM(order_amount) AS revenue FROM orders WHERE region = 'EMEA' AND order_date >= DATEADD(month, -6, CURRENT_DATE) GROUP BY 1 ORDER BY 1",
  "created": {
    "on": "2026-05-27T12:45:00Z",
    "by": "[email protected]"
  }
}

Cross-entity metrics

Cross-entity metrics are metrics that can combine attributes from more than one entity, described in Create, import and manage Semantic Models.

Field	Type	Required	Description
name	string	Yes	Name of the metric
description	string	Yes	Description of the metric
pseudoSQLExpression	string	Yes	Aggregation expression, which can reference attributes from several entities
llmInstructions	string	Yes	LLM instructions for this metric

Unlike entity-level metrics, description and llmInstructions are required for cross-entity metrics.

Example:

{
  "name": "average_order_value",
  "description": "Average revenue per order",
  "pseudoSQLExpression": "SUM(orders.order_amount) / COUNT(DISTINCT orders.order_id)",
  "llmInstructions": "Prefer when the user asks for AOV or average basket size."
}

Glossary

The glossary is a collection of business terms, optionally bound to entities, attributes, metrics or filters, described in Create, import and manage Semantic Models.

Glossary terms

Field	Type	Required	Description
id	string	Yes	Unique identifier of the term
term	string	Yes	The term or phrase
description	string	No	Explanation of the term
source	string	Yes	MANUAL or EXTRACTED (from a business document)
userModified	boolean	No	Whether the term was edited by a user after creation
synonyms	array of strings	No	Alternative terms
created	object	No	See Creation and modification tags
modified	object	No	See Creation and modification tags
privateEditorData	object	No	Editor-internal data for this term

Example:

{
  "id": "9f5dfb35-2d8c-4f11-b94d-7a6f95d2b302",
  "term": "AOV",
  "description": "Average order value, calculated as total revenue divided by number of orders",
  "source": "MANUAL",
  "userModified": true,
  "synonyms": ["average basket size", "avg order value"],
  "created": {
    "on": "2026-05-27T12:50:00Z",
    "by": "[email protected]"
  },
  "privateEditorData": {}
}

Glossary bindings

A binding links a glossary term to an entity, or to a specific attribute, metric or filter of that entity.

Field	Type	Required	Description
termId	string	Yes	id of the bound glossary term
targetEntityClass	string	Yes	Name of the target entity
targetType	string	Yes	ENTITY_CLASS, ATTRIBUTE, METRIC or FILTER
targetName	string	No	Name of the target attribute, metric or filter; null when targetType is ENTITY_CLASS
created	object	No	See Creation and modification tags

Examples:

A term bound to an attribute:

{
  "termId": "9f5dfb35-2d8c-4f11-b94d-7a6f95d2b302",
  "targetEntityClass": "orders",
  "targetType": "ATTRIBUTE",
  "targetName": "order_amount",
  "created": {
    "on": "2026-05-28T09:12:00Z",
    "by": "[email protected]"
  }
}

A term bound to an entire entity, with no targetName:

{
  "termId": "9f5dfb35-2d8c-4f11-b94d-7a6f95d2b302",
  "targetEntityClass": "orders",
  "targetType": "ENTITY_CLASS",
  "targetName": null,
  "created": {
    "on": "2026-05-28T09:12:00Z",
    "by": "[email protected]"
  }
}

Indexing settings

Row and value sampling limits applied by the indexing process described in Create, import and manage Semantic Models.

Field	Type	Default	Description
maxDistinctValuesPerAttribute	integer	1000	Maximum number of distinct values retained per attribute
maxScannedRowsForSQLDatasets	integer	-1	Maximum rows scanned for SQL datasets; -1 means no limit
maxScannedRowsForNonSQLDatasets	integer	1000000	Maximum rows scanned for non-SQL datasets

Example:

{
  "maxDistinctValuesPerAttribute": 1000,
  "maxScannedRowsForSQLDatasets": -1,
  "maxScannedRowsForNonSQLDatasets": 1000000
}

SQL generation config

Version-level configuration for SQL generation, matching the settings of the Semantic Model Query Tool when it is used from the Playground.

Field	Type	Required	Description
instructions	string	No	Model-level LLM instructions, set in the Instructions tab
vocabularyTermIds	array of strings	No	ids of the glossary terms marked as used, set in the glossary’s Used tab
maxRowsPerQuery	integer	No	Maximum rows the LLM has access to from a query’s results
sourcesRecordsLimit	integer	No	Maximum rows displayed in sources
artifactsRecordsLimit	integer	No	Maximum rows included in artifacts
agentRecursionLimit	integer	No	Maximum agent recursion depth, when Agent mode is enabled

Example:

{
  "instructions": "When comparing periods, aggregate by calendar month and use the order_date field unless the user specifies otherwise.",
  "vocabularyTermIds": ["9f5dfb35-2d8c-4f11-b94d-7a6f95d2b302"],
  "maxRowsPerQuery": 1000,
  "agentRecursionLimit": 25
}

Private editor data

Version-level state used by the Semantic Model editor.

Field	Type	Required	Description
llmId	string	No	LLM used for SQL generation in the Playground
embeddingLlmId	string	No	Embedding LLM used for semantic value matching
agentMode	boolean	No	Whether to use the agentic SQL generation workflow

Example:

{
  "llmId": "openai:gpt-4o",
  "embeddingLlmId": "openai:text-embedding-3-small",
  "agentMode": true
}