TypeSchema: enhance profile representation

[ryukzak]

Problem: currently TS and PY profile generation have a lot of duplicate code. We need to improve TypeSchema for profile representation to simplify codegen for profiles by providing detailed instructions on how it should be done. The size of language-specific generators should reduce dramatically.

[ryukzak]

Where the duplication actually lives

I mapped the non-syntactic logic in both generators. The TS and PY profile writers are ~2.8k and ~2.4k lines respectively, and the bulk of them is the same derivation from TypeSchema re-implemented twice — only the emitted string templates differ. Concretely, the following logic exists in both src/api/writer-generator/typescript/* and src/api/writer-generator/python/*:

Duplicated derivation (per concern)

• Validation rules — profile-validation.ts in both languages walks snapshot.fields and derives the identical rule set: excluded, required, valueConstraint→fixed-value, enum routed to warnings/errors by isOpen, mustSupport && !required→warning, reference→resolved target-type names, slice cardinality, required-inside-slice, prohibited choice instances, required choice declarations. Only the call syntax differs (...validateRequired(...) vs errors.extend(validate_required(...))).
• Slice modeling — both re-resolve the field's base type to collect choice-declaration names, subtract match keys + choice names to get the effective required-beyond-match set, call constrainedChoice, detect the type-discriminator (discriminator.some(d => d.type === "type")), parse slice.match to pull the discriminating resourceType, compute the unbounded flag (array && max ∈ {0, undefined}), and decide which required slices are auto-createable.
• Extension shape — both classify each extension into complex / single-value / generic, split ext.path on . filtering "extension" to get the mount path, compute useUpsert from max === "1", derive value[x] field names/types, and derive sub-extension isArray/isRequired from raw min/max.
• Factory / constructor shape — both partition fields into constructor params vs auto-fields vs fixed-fields, promote single-choice required declarations, back-fill base-resource required fields (re-resolving the base schema), and build choice sibling groups for mutual-exclusion clearing.
• Naming / collision — both derive profile class names, module names, and slice/extension method base names (from nameCandidates.recommended), plus value-field names. pyProfileClassName is even documented as "mirrors tsProfileClassName exactly."

Evidence that this is already causing drift

The Python collectValidateBody has diverged from the TS collectRegularFieldValidation: it does not emit validateSliceFields (required fields inside a matched slice, incl. the constrained-choice variant) and does not emit validation for snapshot.inheritedRequiredFields. Both are present on the TS side. This is exactly the failure mode the issue predicts — the same rule table, maintained in two places, has already fallen out of sync.

Root cause

SnapshotProfileTypeSchema stops at raw, partially-resolved data. Each generator finishes the resolution itself, at generation time. Several derivations are recomputed even within a single language (the type-discriminator flag is computed in 4 places; the required-beyond-match set in 3). And constrainedChoice is resolved on-demand via the index rather than stored on the slice.

Proposed direction: push resolution into TypeSchema

Enrich the snapshot so generators only render — no schema-graph walking, no match-literal parsing, no cardinality re-derivation. Candidate additions:

• Resolved SliceModel on each slice: { baseType, elementType, matchLiterals, isTypeDiscriminated, typeDiscriminatorResource, isUnbounded, requiredBeyondMatch, constrainedChoice, autoCreatable }.
• Resolved ExtensionModel on each extension: { kind: "complex" | "single-value" | "generic", targetPath: string[], useUpsert, valueField: { name, type }, subExtensions: [{ name, url, valueType, isArray, isRequired }], profileRef }.
• A validation plan: an ordered list of typed, language-neutral rules — Required / Excluded / FixedValue / Enum{severity} / MustSupport / Reference{targets} / SliceCardinality / SliceFields / ChoiceRequired. Reference targets already resolved to names; enum severity already decided. Generators map rule→one line.
• A factory plan: precomputed params, autoFields, fixedFields, promotedChoices, choiceSiblingGroups — reusing the already-present inheritedRequiredFields for the constructor surface instead of re-resolving the base schema.
• Extend the nameCandidates pattern to method names, so each language applies only casing (camelCase vs snake_case) rather than re-deriving base names.

The precomputation already has a home: src/typeschema/core/ (see name-candidates.ts for the existing precedent) and the snapshot builder in src/typeschema/utils.ts.

Scope / what stays language-specific

Left in the writers: token/keyword escaping and casing, type mapping (FHIR primitive → string/str), and idiom-specific shaping (e.g. Pydantic list-wrapping in normalizeMatchForPython, TS Omit<>/intersection input types, spread vs .extend()). Everything else moves behind the data model. Expected outcome: the language writers shrink to thin renderers over a fully-resolved plan, and cross-language drift becomes structurally impossible for the covered concerns.

(File references and a full per-file inventory available on request.)