> ## Documentation Index > Fetch the complete documentation index at: https://developers.askparable.com/llms.txt > Use this file to discover all available pages before exploring further. # catalog > The workspace's semantic catalog, proxied unchanged from query-layer v2. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v2/catalog openapi: 3.0.3 info: title: Parable API description: >- The REST API for your Parable workspace: manage connectors and taps, explore your data catalog, upload artifacts, and administer users and roles. version: v1 servers: - url: https://api.askparable.com description: Production security: [] paths: /api/v2/catalog: get: tags: - catalog-v2 summary: catalog description: The workspace's semantic catalog, proxied unchanged from query-layer v2. operationId: CatalogV2CatalogHandler parameters: - description: >- Workspace slug. Overrides subdomain-based workspace resolution when provided. in: header name: X-Tenant required: false schema: example: acme type: string - description: Optional request correlation ID echoed back in the response. in: header name: X-Request-ID required: false schema: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/SemanticCatalogResponse' links: $ref: '#/components/schemas/ResponseLinks' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta type: object description: Successful response '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal server error security: - bearerAuth: [] components: schemas: SemanticCatalogResponse: description: The workspace's semantic catalog. properties: catalogVersion: description: |- Structure-only catalog fingerprint (planner version + plans + provider roots + views). Data movement never bumps it; clients may key caches on (tenantSlug, catalogVersion). type: string contractVersion: description: >- Catalog metadata contract version (`parable.metadata.contract_version`). type: string tables: items: $ref: '#/components/schemas/SemanticCatalogTable' type: array tenantSlug: description: >- Workspace the catalog belongs to (from the request; SYSTEM-1782). Same type as Workspace.slug, the field it references. type: string views: items: $ref: '#/components/schemas/SemanticCatalogView' type: array required: - tenantSlug - catalogVersion - contractVersion - tables - views type: object ResponseLinks: properties: first: nullable: true type: string last: nullable: true type: string next: nullable: true type: string prev: nullable: true type: string type: object ResponseMeta: properties: requestId: description: Unique identifier for the request type: string totalCount: description: Total count of items for paginated responses nullable: true type: integer required: - requestId type: object Error: properties: error: type: string type: object SemanticCatalogTable: description: One served base table. properties: catalog: description: >- DataFusion catalog the table registers under (`providers`, `providers_quarantine`, or `providers_quality`). Quarantine mirrors and quality history siblings share connector schema naming with their provider table; the catalog carries meaning. type: string fields: items: $ref: '#/components/schemas/SemanticCatalogField' type: array importedForeignKeys: description: Foreign keys imported by this table. Empty when none are resolved. items: $ref: '#/components/schemas/SemanticCatalogForeignKey' type: array logicalName: description: Logical table name inside the connector schema. type: string materialized: description: |- Whether the writer has materialized the physical table. Null until an annotation source answers (unknown, never false-by-default). type: boolean primaryKey: $ref: '#/components/schemas/SemanticCatalogPrimaryKey' description: |- Ordered logical columns for the table's primary key. Null when the planner does not expose a complete primary key. schemaName: description: |- Per-connector schema the table registers under: the connector slug sanitized for SQL identifiers (`-` becomes `_`, e.g. `google-drive` registers as `google_drive`), which stays within the Connector.Slug pattern. type: string statsRowCount: description: Row count from the annotation source; null when unknown. format: int64 type: integer tableKind: $ref: '#/components/schemas/CatalogTableKindEnum' description: Position in the tap's plan; Flight `parable.annotation.table_kind`. tapKind: $ref: '#/components/schemas/CatalogTapKindEnum' description: >- Catalog tap-kind vocabulary (EDR-0021 kinds plus `derived` for platform-synthesized families); Flight `parable.annotation.tap_kind`. validationRates: description: |- Per-column validation rates keyed by logical column name. Empty when no annotation source answered. items: $ref: '#/components/schemas/SemanticCatalogValidationRate' type: array watermark: description: Completeness watermark ("complete through T"); null when unknown. type: string watermarkStale: type: boolean required: - catalog - schemaName - logicalName - tableKind - tapKind - validationRates - importedForeignKeys - fields type: object SemanticCatalogView: description: |- One opt-in convenience view (LOG-3). The output schema is a planning product resolved from the workspace session at request time, exactly as Flight GetTables serves it. properties: fields: items: $ref: '#/components/schemas/SemanticCatalogField' type: array logicalName: type: string schemaName: description: |- Views register under their parent table's per-connector schema (the sanitized connector slug, same as SemanticCatalogTable.schemaName). type: string required: - schemaName - logicalName - fields type: object SemanticCatalogField: description: |- SRV-2 (PARABLE-296): the runtime-computed logical catalog served as psgen / ParableSchema semantic types. This REST projection and the Flight SQL GetTables metadata are two views of the same computation (`ProviderCatalog::build`); the field-for-key mapping lives in services/query-layer/src/metadata_contract.rs. Pool addressing is docs/internal/decisions/edr/0080-three-pool-data-catalog.mdx. Null / unknown semantics follow the metadata contract: an omitted (null) annotation field means *unknown / not yet computed*; a present value is authoritative. Identity fields (tableKind, tapKind, contractVersion) are always present. One logical column of a served table or view. properties: arrowType: description: |- Deterministic Arrow DataType rendering (Arrow's canonical Display form). Deliberately a string, not an enum: nested and parameterized types render their full parameters (`List(Field { .. Utf8 .. })`, `Timestamp(Nanosecond, Some("UTC"))`, `Map(...)`), so the value set is open -- it is the exact type served in the Flight IPC schema for the same column, which an enum of type families could not carry. type: string hidden: description: |- True on internal/ops columns deliberately exposed in the logical schema (quarantine `_parable_*` envelope columns). Main-table envelope columns are excluded from the schema entirely, not flagged. type: boolean name: description: |- Logical column name (lowercased source path segments joined with `__`), exactly as served by Flight GetTables. type: string nullable: type: boolean poorPruning: description: |- True on columns whose physical representation defeats data skipping (JSON-encoded, native struct/array, capture buckets). Mirrors the Flight `parable.annotation.poor_pruning` field metadata key. type: boolean scalarRef: description: >- Canonical name of the column's semantic scalar (e.g. `Contact.Email`), exactly the Flight `parable.scalar.canonical_name` field metadata value; null when the column carries no semantic scalar. Consumers needing a JSON-Schema pointer can prefix `#/definitions/scalars/`. type: string required: - name - arrowType - nullable - hidden - poorPruning type: object SemanticCatalogForeignKey: description: An imported foreign key from this table to another served table. properties: referencedColumns: items: type: string type: array referencedSchema: description: An opaque identifier for a connector definition type: string referencedTable: type: string sourceColumns: items: type: string type: array required: - sourceColumns - referencedSchema - referencedTable - referencedColumns type: object SemanticCatalogPrimaryKey: description: Ordered logical columns forming a table's primary key. properties: columns: items: type: string type: array required: - columns type: object CatalogTableKindEnum: description: |- Position of a served table in a tap's mapping plan (query-layer v2 catalog metadata contract). Mirrors the vocabulary served under the Flight `parable.annotation.table_kind` schema metadata key; the Rust source of truth is `services/query-layer/src/metadata_contract.rs` (`CatalogTableKind`). enum: - main - quarantine - child - child_quarantine type: string CatalogTapKindEnum: description: >- The tap-kind vocabulary of the query-layer v2 catalog metadata contract, served under the Flight `parable.annotation.tap_kind` schema metadata key. The Rust source of truth is `services/query-layer/src/metadata_contract.rs` (`tap_kind_label` / `TAP_KIND_DERIVED`). This is a superset of TenantConnectorTapKindEnum: served tables are either backed by a workspace connector tap (the EDR-0021 kinds) or synthesized by the platform (DERIVED). enum: - override - custom - artifact - derived type: string SemanticCatalogValidationRate: description: |- Per-column validation rate (logical column name -> rate string), from the Flight `parable.annotation.validation_rate.{column}` keys. properties: column: type: string rate: type: string required: - column - rate type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ````