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.

Explorer and DevTools coverage

The explorer publishes schema identity for every renderable family currently used by the Blueprint grammar:

• Blueprint, module, module export, descriptor, entity, facet, and field;
• relationship, lifecycle, transition, action, rule, condition, actor set, and field predicate;
• effect, evidence, audit, action capture, action event, and action error;
• derived value, subscription, projection, and projected field;
• task template, invariant, action plan, and action-plan step.

Entity DevTools groups those declarations under the existing Facets, Fields, Actions, Projections, Lifecycle, and Rules tabs. Origin graphs remain internal assembly diagnostics and are not a separate entity-facing vocabulary tab.

Renderer rules

1. Reject missing or unknown schema.schemaType; do not guess.
2. Render title first and show code where exact developer identity helps.
3. Preserve name and code exactly; never title-case qualified codes.
4. Do not create a parallel label field in protocol or catalog models.
5. Keep search, sort, and filter local when the complete catalog is already in memory; server-backed entity data keeps its declared query adapter.
6. Use the schema envelope consistently in generated JSON, samples, fixtures, OpenAPI-adjacent inspectors, and documentation.

Compatibility changes

The hardened contract intentionally removes ambiguous aliases:

• vocabulary and query descriptors use name and title, not label;
• projection results use structural shape, not result kind;
• collection layouts use table and grid, not separate grid and cards;
• module physical database schema is database_schema, leaving schema for the vocabulary identity envelope.

Clients and fixtures should migrate forward rather than supporting both names, because accepting both would recreate the ambiguity this contract removes.

Publishing a vocabulary change

Before publishing a vocabulary change:

• add or update its BlueprintVocabularySchemaTypes entry;
• emit schemaType, name, and title, plus code when addressable;
• update strict wire round-trip and explorer coverage tests;
• update Studio rendering without adding a second discriminator;
• run static analysis and the affected Dart and Flutter test suites;
• update this contract and the complete grammar when terminology changes.