# Customize with enrichments



## What you'll build [#what-youll-build]

The petstore project from [tutorial 02](/docs/using/tutorials/02-multiple-generators),
now with a form generator added and customized through enrichments:
operation-specific form titles, submit-button labels, and field
labels.

## Prerequisites [#prerequisites]

* The `petstore` project from [tutorial 02](/docs/using/tutorials/02-multiple-generators).
* Familiarity with the [enrichments concept](/docs/concepts/enrichments)
  (skim it; this tutorial gives concrete steps).

## Step 1: Find the generator's enrichment shape [#step-1-find-the-generators-enrichment-shape]

Install the form generator:

```bash
skmtc install @skmtc/gen-shadcn-form petstore
```

Each generator declares its enrichment shape in `src/enrichments.ts`.
For `gen-shadcn-form`, the shape is roughly:

```jsonc
{
  "title": "string",
  "description": "string",
  "submitLabel": "string",
  "fields": [
    {
      // binds this entry to a request-body property — the path IS the join key
      "moduleSelect": { "schemaPath": ["name"] },
      "label": "string",
      "placeholder": "string"
    }
  ]
}
```

All keys are optional — provide only what you override.

The full schema is documented at [gen-shadcn-form's reference](/docs/reference/stock-generators/gen-shadcn-form).

## Step 2: Add enrichments to client.json [#step-2-add-enrichments-to-clientjson]

`gen-shadcn-form` is an OAS operation generator, so its routing
keys are the literal OpenAPI `path` and lowercase `method` —
**not** `operationId`. For the petstore, `addPet` is `POST /pet`
and `updatePet` is `PUT /pet`.

Edit `.skmtc/petstore/.settings/client.json`:

```jsonc
{
  "source": "./openapi.json",
  "settings": {
    "basePath": "src/generated",
    "enrichments": {
      "@skmtc/gen-shadcn-form": {
        "/pet": {
          "post": {
            "main": {
              "title": "Add a new pet",
              "submitLabel": "Add to inventory",
              "fields": [
                { "moduleSelect": { "schemaPath": ["name"] }, "label": "Pet name", "placeholder": "Fluffy" },
                { "moduleSelect": { "schemaPath": ["category"] }, "label": "Category" }
              ]
            }
          },
          "put": {
            "main": {
              "title": "Edit pet details",
              "submitLabel": "Save changes"
            }
          }
        }
      }
    }
  }
}
```

The routing path is `[generatorId][path][method][variant]` for OAS
operation generators — the override sits under the `variant` key
(`main` by default). See
[enrichments shape reference](/docs/reference/settings/enrichments-shape)
for all three routing shapes.

Two validation behaviors worth knowing before you edit: a
wrongly-typed value (a number where `title` expects a string) fails
that operation's generation — the run completes, and the manifest
records the error with the path. A misspelled key can't fail
anything (the schema ignores unknown keys), so the engine warns
about it instead — step 5 shows that warning in action.

## Step 3: Regenerate [#step-3-regenerate]

```bash
skmtc generate petstore
```

No need to rebundle — `client.json` is runtime config, not bundle
code.

## Step 4: Verify the customization landed [#step-4-verify-the-customization-landed]

Look at the generated form:

```bash
cat src/generated/pet/addPet.generated.tsx
```

The form's `<h2>` text is now "Add a new pet", the submit button
reads "Add to inventory", and the `name` field's label is "Pet
name". Other operations use the form generator's defaults
(derived from the OAS path and verb).

## Step 5: Typo a key on purpose [#step-5-typo-a-key-on-purpose]

Misspell one override and watch the engine catch it. In
`client.json`, change `"submitLabel"` to `"submitLabl"` and
regenerate:

```bash
skmtc generate petstore --json > out.json
jq '.manifest.enrichmentWarnings' out.json
```

The run completes (warnings never affect output), and the manifest
names the problem — an `UNKNOWN_ENRICHMENT_KEY` warning carrying the
full routing path and a suggestion (`submitLabl` → did you mean
`submitLabel`?). The same block prints as "Enrichment warnings" in
the normal command output. Typos in the routing keys (a wrong path or
method) surface the same way, as `UNCONSUMED_ENRICHMENT`.

Fix the key back and regenerate before moving on.

## What just happened [#what-just-happened]

Your `client.json` entry was routed to the form generator by the
path `[generatorId][path][method][variant]` and validated against
the shape the generator declares. Where you provided a value (the
`title` for `POST /pet`), it overrode the generator's default; where
you didn't, the defaults applied — which is why the other operations'
forms are unchanged. Configuration reached generated output without
you touching any code.

How enrichments are declared and routed — including what generator
authors do on the other side of this contract — is the
[enrichments concept](/docs/concepts/enrichments).

## Next steps [#next-steps]

* [How to configure enrichments](/docs/using/how-to/configure-enrichments) —
  targeted reference for adding more enrichment entries
* [Enrichments concept](/docs/concepts/enrichments) — the
  mental model
* [Tutorial: Cloning a generator](/docs/authoring/tutorials/01-cloning-a-generator) —
  when enrichments aren't enough and you need source-level
  customization