Vocabulary Identity and Display Contract

Blueprint declarations are both executable language elements and objects that people inspect in Studio, DevTools, generated documentation, and protocol clients. Every renderable vocabulary item therefore carries one consistent identity contract.

This document is normative for serialized Blueprint vocabulary and for UI adapters that render it.

Canonical identity

Every serialized vocabulary item contains a schema object with these fields:

Property	Required	Meaning
schemaType	Yes	The only semantic discriminator. It selects the vocabulary family.
name	Yes	Stable declaration-local name. Preserve its exact case and punctuation.
title	Yes	Human-facing display string. Author it explicitly or derive it deterministically during assembly.
code	No	Exact qualified developer identity, such as iam.user or mfg.equipment.cleaning.release.
pluralTitle	No	Human-facing plural used by collections.
description	No	Explanatory copy for inspectors and documentation.
i18nKey	No	Localization lookup key when display strings are translated.

label is not a vocabulary identity property. Widget APIs may use the word label for form captions, buttons, accessibility text, error remedies, or key/value rows, but protocol models and reusable catalog descriptors use name and title.

{
  "schema": {
    "schemaType": "vyuh.blueprint.entity",
    "name": "user",
    "title": "User",
    "pluralTitle": "Users",
    "code": "iam.user",
    "description": "A person who can act in the system."
  },
  "table": "users"
}

What each value is for

Use schemaType in an exhaustive switch when behavior depends on whether an item is an entity, facet, action, relationship, effect, or another vocabulary family. Never infer that family from a runtime class name, kind, type, a qualified-code prefix, or which fields happen to be present.

Use title in business-facing headings, table columns, tabs, menus, option pickers, reports, and detail rows. Use code beside it on developer-facing surfaces where exact addressing matters. Use name for stable local lookup, saved configuration, and declaration references.

Domain attributes remain ordinary properties after the vocabulary family is known. For example, a relationship's kind, a rule's phase, and an evidence item's evidence_kind describe behavior inside an already identified schema type; they do not replace schema.schemaType.

Projection results

Projection results preserve the sealed typed hierarchy:

• CollectionResult contains many ProjectionObject values and paging;
• ItemResult contains one value or null;
• CustomProjectionResult is the registered extension envelope.

The wire property shape selects only that structural envelope:

{
  "schema": {
    "schemaType": "iam.user:detail",
    "name": "user_detail",
    "title": "User Detail",
    "columns": [
      {"name": "id", "title": "ID", "kind": "string", "nullable": false},
      {"name": "name", "title": "Name", "kind": "string", "nullable": false}
    ]
  },
  "shape": "item",
  "data": {"id": "user-1", "name": "Quality Reviewer"}
}

shape is structural, not semantic. schema.schemaType remains the only semantic discriminator. Projection columns follow the same naming rule: name is stable identity and title is the visible heading.

Collection layout terminology

Blueprint has two canonical general-purpose collection layouts:

Layout	Purpose
TableUI	Ordered columns, visibility, width, pinning, and tabular comparison.
GridUI	Responsive columns of card-shaped items configured by CardContentUI.

cards is not a second layout beside grid. A card is the content container inside a grid item. Saved views select a named Table or Grid layout and then store query, sorting, grouping, and layout-specific configuration.