[docs] Add Catalog Design Best Practices: Anti-Corruption Layer modeling, semantic grain size, and protocol vs. data versioning

When onboarding existing enterprise codebases to A2UI, teams consistently run into two architectural friction points when authoring their Catalog:

DTO Porting & Primitive Obsession: Teams run automated OpenAPI/Swagger or Protobuf generators to export backend DTOs straight into the agent catalog. Those wire formats rely heavily on loose primitives (String status, double discount, Map<String, dynamic>). Because the schema describes wire shape without domain invariants, the LLM generates invalid combinations (for example, negative tax rates or conflicting status strings), leading teams to bury their codebase in defensive runtime validators.
Semantic Grain Size Extremes: Without guidance, catalogs swing between overly granular primitives (add(), multiply(), requiring the LLM to compose fragile arithmetic ASTs in JSON) and overly coarse "god functions" (submitFullCheckout(), stripping away generative UI flexibility).

Suggested Guidance Additions

Adding a short Catalog Design Best Practices section to the A2UI documentation would save teams weeks of trial and error:

Treat the Catalog as an Anti-Corruption Layer (ACL): Curate a semantic interface designed specifically for cognitive reasoning rather than mirroring raw backend DTOs. Project existing domain invariants (closed enums, sealed state types, database CHECK bounds, and min/max test boundaries) into argumentSchema using strict enum, minimum, and maximum constraints ("parse, don't validate").
Target Complete, Inviolable Domain Rules: Size FunctionImplementation functions around complete domain calculations (for example, calculateCartItemCost or validatePostalCode) that encapsulate business-rule ordering without dictating layout topology.
Separate Catalog Versions from Data Versions: Keep the Catalog ID/version strictly tied to the structural schema contract (components, function names, and parameter schemas), while carrying runtime data freshness (such as updated tax tables or postal directories) via monotonic version tags on DataModel updates. Updating runtime data should never require bumping the catalog version and forcing mid-flight agent renegotiation.

From triage bot:

Triage suggestion:

For humans

Summary:
The issue asks for a "Catalog Design Best Practices" section in the docs: design the catalog for the model instead of mirroring backend DTOs, put domain limits into argumentSchema with enum, minimum and maximum, size functions around complete domain rules, and keep catalog versions separate from data versions.

Why flagged for triage:
This issue has external input but no priority label yet.

Suggestion:
Set P3: it is a good docs request, but it reports no defect and is not on the roadmap. The best place for it is the Defining a catalog guide, which covers custom functions and input validators but gives no design guidance. The third point needs care: the protocol has no version tag on data model updates, so the docs could describe it only as an app-level convention, not as a protocol feature. #4162, by the same author, asks for related docs on client-side functions.

Add labels: type: feature/enhancement, P3, component: documentation
Related issues: [docs] Clarify expression purity, fail-loudly argument contracts, and server-side transactional authority for client-side functions #4162

To adjust and apply this suggestion, run in your a2ui checkout:

tools/internal/triage_new/triage_ui.sh https://github.com/a2ui-project/a2ui/issues/4163

For software

<a2ui>
root = TriageSuggestion(
  summary="""The issue asks for a "Catalog Design Best Practices" section in the docs: design the catalog for the model instead of mirroring backend DTOs, put domain limits into `argumentSchema` with `enum`, `minimum` and `maximum`, size functions around complete domain rules, and keep catalog versions separate from data versions.""",
  reason="This issue has external input but no priority label yet.",
  suggestion="""Set P3: it is a good docs request, but it reports no defect and is not on the [roadmap](https://github.com/a2ui-project/a2ui/blob/8bf644a37d680a227296b8c0849a7f4b328b8b73/docs/public/roadmap.md). The best place for it is the [Defining a catalog](https://github.com/a2ui-project/a2ui/blob/8bf644a37d680a227296b8c0849a7f4b328b8b73/docs/site/src/content/docs/guides/defining-a-catalog.mdx) guide, which covers custom functions and input validators but gives no design guidance. The third point needs care: the protocol has no version tag on data model updates, so the docs could describe it only as an app-level convention, not as a protocol feature. #4162, by the same author, asks for related docs on client-side functions.""",
  added_labels=["type: feature/enhancement", "P3", "component: documentation"],
  related_issues=[4162]
)
</a2ui>

_{🤖 Agent-generated}

@RandalSchwartz

Hi @RandalSchwartz, Thank you for raising the issue. We appreciate you taking the time to share your thoughts with us.
Hi @gspencergoog, could you please take a look?

Navigation Menu

Repository navigation

[docs] Add Catalog Design Best Practices: Anti-Corruption Layer modeling, semantic grain size, and protocol vs. data versioning #4163

Suggested Guidance Additions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[docs] Add Catalog Design Best Practices: Anti-Corruption Layer modeling, semantic grain size, and protocol vs. data versioning #4163

Description

Suggested Guidance Additions

Activity

polina-c commented on Nov 12, 2026

Varun-S10 commented on Nov 12, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions