Schemas

Get the concept card for a field

One read that tells a consumer what a field MEANS and how it BEHAVES, so an agent can choose the right concept without trial and error: definition (curated description + extraction instruction), synonyms and merge aliases, maturity, where it occurs (document / occurrence counts, first/last seen, document-type spread), the value distribution (top values with counts and shares, distinct count), schema usage, and its identity links (superseded_by, absorbed concepts).

Value statistics are Sources-IAM filtered as the key's minting user and include occurrences still bound to concepts merged INTO this one, so the card is complete while a merge's lazy repoint is in flight.

get/v1/fields/{id}/card

Request

  • Base URL: https://api.talonic.com
  • URL: https://api.talonic.com/v1/fields/{id}/card
  • Auth: HTTP bearer

Path parameters

idstring uuid required
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Resource UUID.

Query parameters

follow_redirectsboolean

Walk superseded_by to the live survivor and describe that concept.

Response

Concept card.

idstring uuid required
canonical_namestring required
maturity'core' | 'proven' | 'candidate' required

Named maturity level — the contract a consumer caching the vocabulary can rely on (tier is the frozen numeric twin: core = 1, proven = 2, candidate = 3).

  • core: universal, fully trusted; safe to bind schemas, dashboards and downstream models to. Demotion is hysteresis-guarded and always emits field.demoted.
  • proven: recurring and useful; stable id, name may still be groomed (field.renamed / field.merged announce it).
  • candidate: newly discovered; may be merged, renamed or expire with no notice beyond the event feed. Do not hard-code.
admission_state'canonical' | 'provisional'
descriptionstring nullable

Curated semantic description of the concept.

synonymsstring[]

Names folded onto this concept by merges and cleanup; all resolve via GET /v1/fields/resolve.

display_namestring required

Human-readable label, always present. A stored display name wins; otherwise it is derived from canonical_name, e.g. invoice_number → Invoice Number.

data_typestring required
tierinteger required
cluster_namestring nullable
occurrence_countinteger required
master_instructionstring nullable
created_atstring date-time required
updated_atstring date-time
redirected_fromstring[]

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "canonical_name": "invoice_number",
  "display_name": "Invoice Number",
  "data_type": "string",
  "created_at": "2026-04-25T14:30:00.000Z",
  "updated_at": "2026-04-25T14:30:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.