Discover the data available for questions

Purpose

Give staff a clear inventory of queryable records and a description of the fields and relationships available to them.

How It Works

Staff begin by browsing the available datasets. The catalog helps them distinguish missing access from missing data. Opening an available dataset supplies the information used to build a question. Workspace labels and custom fields make that description recognizable to the customer. Applications maintain the declarations behind this shared vocabulary. Registration reports problems before a declaration can be used. A dataset description supplies starting choices for a screen without silently adding them to execution. The product should decide when more granular field and row restrictions become part of this contract.

Relationships

Dataset discovery supplies the descriptions used by execution, custom tables and reusable recipes.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Staff can distinguish available datasets from missing access.Descriptions expose permitted query information.Metadata changes appear in the next description.
Surfaces: consoleapijob
Intent sources: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 1services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 5services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 6services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 7services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 18services-platform:docs/queries/semantic-query-layer.md#6.5 Visibility versus access (Andrew, 2026-10-21, CRM-ACC-0064)

Controls

30 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-005 TC-CHG-006 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-006 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.queries.read`	api	tenant
`<application>.<dataset>.query (the owner's key, e.g. crm.contacts.query)`	service	tenant
`<application>.<records>.read where the owner declares it (e.g. crm.organizations.read)`	service	tenant
`platform.custom-records.query (scoped to custom_object:<object key>)`	service	record

Business Rules

12 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 12 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	The dataset catalog includes all registered workspace datasets, marks each person’s access, and counts usable datasets per application rather than hiding unauthorized entries. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 1 proved by `ATS-PFM-QRY-001-01`, `ATS-PFM-QRY-001-14`, `TST-PFM-QRY-225`	permission	api, service	test services-platform:modules/queries/tests/e2e/datasets.e2e.spec.js#answers each dataset with whether this caller may use it
`02`must prove Confirmed	Dataset descriptions and runs require query-surface access and the dataset’s query permission; missing access is refused with the permission named, while an unregistered dataset is not found. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 1 proved by `ATS-PFM-QRY-001-02`, `ATS-PFM-QRY-001-13`, `ATS-PFM-QRY-005-17`, `TST-PFM-QRY-225`	permission	api, service	test services-platform:modules/queries/tests/e2e/datasets.e2e.spec.js#refuses a dataset the caller holds no query permission for as 403
`03`must prove Confirmed	When the dataset also declares a record-read permission, readers need both permissions, and a denied read permission makes its query surfaces unavailable despite a query grant. origin: services-platform:docs/queries/semantic-query-layer.md#6.5 Visibility versus access (Andrew, 2026-10-21, CRM-ACC-0064) proved by `ATS-PFM-QRY-001-03`, `TST-PFM-QRY-254`	permission	service	test services-platform:modules/queries/tests/integration/services/describe/dataset-effective-permissions.integration.spec.js#refuses Organizations to a caller denied crm.organizations.read, though the role still grants crm.organizations.query
`04`must prove Confirmed	A dataset query also requires access to its owning application, and a missing application grant produces a refusal naming that permission. proved by `ATS-PFM-QRY-001-04`, `TST-PFM-QRY-224`	permission	api, service	test services-platform:modules/queries/tests/e2e/dataset-effective-permissions.e2e.spec.js#refuses a role holding the dataset key without the application's access key 403, naming the key
`05`must prove Confirmed	A description combines registered fields, workspace custom information and labels with permitted relationships, while excluding physical storage details. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 5 proved by `ATS-PFM-QRY-001-05`, `TST-PFM-QRY-225`, `TST-PFM-QRY-296`	invariant	service	test services-platform:modules/queries/tests/e2e/datasets.e2e.spec.js#tells the console nothing of how a field is stored
`06` Confirmed	The product should expose each registered record column for querying unless its owner records an exclusion reason. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 6	policy	service	documented services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 6
`07`must prove Confirmed	A changed field, label, classification or registration invalidates the relevant cached description so the next request reflects it. origin: services-platform:docs/queries/semantic-query-layer.md#7.4b The description cache [Built, 2026-10-14] (Andrew, 2026-10-14) proved by `ATS-PFM-QRY-001-06`, `TST-PFM-QRY-263`	invariant	service, database	test services-platform:modules/queries/tests/integration/services/describe/description-stamp-coverage.integration.spec.js#describes a custom field the tenant adds on the very next build
`08`must prove Confirmed	Descriptions advertise initial columns, ordering, criteria and discovery statuses, but execution does not add those suggested criteria to a submitted query. proved by `ATS-PFM-QRY-001-07`, `ATS-PFM-QRY-001-12`, `ATS-PFM-QRY-002-17`, `TST-PFM-QRY-262`, `TST-PFM-QRY-276`	policy	service	test services-platform:modules/queries/tests/integration/services/execute/discovery-defaults.integration.spec.js#answers every contact of the tenant whatever its status, nothing having injected the reported criteria
`09`must prove Confirmed	Active custom objects become workspace datasets without deployment and require the custom-record query permission scoped to the particular object. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 18 proved by `ATS-PFM-QRY-001-08`, `TST-PFM-QRY-222`	permission	service	test services-platform:modules/queries/tests/e2e/custom-object-datasets.e2e.spec.js#is refused objects.boats with 403
`10`must prove Confirmed	Application deployments register datasets through an internal invocation, whose response identifies rejected declarations so deployment can report them. proved by `ATS-PFM-QRY-001-09`, `TST-PFM-QRY-225`	lifecycle	service	test services-platform:modules/queries/tests/e2e/datasets.e2e.spec.js#names what it refused in the answer
`11`must prove Confirmed	Registration rejects workspace datasets without a workspace-bearing source and references that cross between workspace and system dataset scopes. proved by `ATS-PFM-QRY-001-10`, `TST-PFM-QRY-332`	validation	service	test services-platform:modules/queries/tests/integration/services/registration/register-query-application.integration.spec.js#refuses a tenant-scoped dataset whose base has no tenant_id, naming the relation and the scope it should declare
`12`must prove Confirmed	Registered record-opening fields must belong directly to the record; unknown fields and selected collection values are rejected. proved by `ATS-PFM-QRY-001-11`, `TST-PFM-QRY-332`	validation	service	test services-platform:modules/queries/tests/integration/services/registration/register-query-application.integration.spec.js#refuses a pick as a link field, because a pick is not a field of the record itself

Scenarios

Id	Given	When	Then	Provenance
`01`	A person may query contacts but lacks organization query access.	They request the dataset catalog.	Contacts is authorized and Organizations remains listed without authorization.	test services-platform:modules/queries/tests/e2e/datasets.e2e.spec.js#marks the datasets of that key authorized in the list, and the others not
`02`	A custom contact field is added after a description is cached.	The workspace requests another contact description.	The description includes the added field.	test services-platform:modules/queries/tests/integration/services/describe/description-stamp-coverage.integration.spec.js#describes a custom field the tenant adds on the very next build

Planning

Implementation

Discover the data available for questions ​

Purpose ​

How It Works ​

Relationships ​