@sumrco/cli 0.2.1 → 0.3.1

package/ai/modules/kontract/resources/authoring/schema-reuse.rf.md

@@ -0,0 +1,492 @@
+---
+category: reference
+name: schema-reuse
+title: Schema Reuse and Shared Components
+description: "How to author API and async schemas with reusable shared components, $ref, Kontract sets, and safe composition so Kontract output stays consistent and avoids duplicated contract shapes."
+label: Schema Reuse
+when: Adding repeated fields, response envelopes, pagination, errors, schedules, config objects, or reviewing generated diffs with duplicated DTO/model shapes
+order: 12
+---
+
+# Schema Reuse and Shared Components
+
+Kontract works best when the spec is designed like a product API, not like a
+collection of copied YAML snippets. If the same concept appears in multiple
+operations or services, define it once and reference it with `$ref`.
+
+This reduces drift in the source specs immediately. It also gives Kontract a
+clear path to emit more shared generated code as the generator evolves.
+
+Before extracting or naming a shared component, choose a name from product
+language. Shared names should stay specific enough for generated DTO/model/SDK
+symbols.
+
+## Local-first promotion model
+
+Keep a schema in the smallest owning place until reuse proves it should move:
+
+1. **Surface-local** — define one-off request, response, and model shapes in the
+   root file's `components.schemas`.
+2. **Capability-local shared** — move the shape into the capability's
+   `shared/` folder when two or more surfaces in that capability reuse the same
+   concept.
+3. **Repo-level shared** — move the shape into `schema/shared/` only when two or
+   more capabilities share the same semantics, lifecycle, and owner.
+
+Do not create shared files only because a shape might become reusable later.
+Shared components are a promotion step, not the default folder for every model.
+
+## What to share
+
+Prefer shared components for concepts that mean the same thing everywhere:
+
+- scalar primitives: UUIDs, ISO dates, slugs, URLs, MIME types, time strings;
+- path/query parameters: `id`, `recipeId`, pagination, date ranges;
+- standard error responses and error body schemas;
+- pagination metadata;
+- common response envelope fields such as `success`, `timestamp`, `path`, and
+  optional `message`;
+- weekly schedules and reusable time-slot shapes;
+- repeated configuration objects, such as measurement units, recipe step labels,
+  display colors, notification settings, or payment settings when they truly
+  share semantics.
+
+Example shared scalar and parameter file:
+
+```yaml
+# schema/shared/common.yml
+components:
+  schemas:
+    UuidString:
+      type: string
+      format: uuid
+    ImageMimeType:
+      type: string
+      pattern: '^image\/(jpeg|png|webp|gif)$'
+    PaginationMeta:
+      type: object
+      required: [page, pageSize, pageCount, total]
+      properties:
+        page:
+          type: integer
+          minimum: 1
+        pageSize:
+          type: integer
+          minimum: 1
+        pageCount:
+          type: integer
+          minimum: 0
+        total:
+          type: integer
+          minimum: 0
+  parameters:
+    id:
+      name: id
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/UuidString'
+```
+
+Use those components from service specs:
+
+```yaml
+parameters:
+  - $ref: ../shared/common.yml#/components/parameters/id
+content:
+  application/json:
+    schema:
+      $ref: ../shared/common.yml#/components/schemas/ImageMimeType
+```
+
+## Protocol scenarios for reuse
+
+Pick the protocol scenario before extracting shared components:
+
+1. **API-only** — share HTTP schemas, parameters, responses, envelopes,
+   pagination, errors, and scalar constraints through API schema components.
+2. **async-only** — share message payload schemas, message enums, scalar
+   constraints, and value objects through async schema components or
+   capability-local model fragments.
+3. **API + async** — keep protocol layers separate and share only neutral
+   components with identical meaning. The safest cross-protocol sharing is
+   usually enums, IDs, slugs, scalar value objects, and simple payload shapes.
+
+Do not create cross-protocol shared files only because API schema and async schema
+payloads look similar today. Shared components must have the same product
+meaning and owner.
+
+## API-only reuse
+
+If the repo only has API schema sources, keep one-off schemas in the owning
+API schema surface. Use a capability-local `shared/` folder only after multiple
+surfaces in that capability reuse the same concept. Use `schema/shared/` only
+after multiple capabilities share the same concept.
+
+```text
+schema/
+  bookstore/
+    main.api.yml
+    catalog.api.yml
+    reviews.api.yml
+    shared/
+      enums.yml                 # reused by catalog and reviews
+      components.yml
+  shared/
+    errors.yml                  # reused by multiple capabilities
+    pagination.yml
+```
+
+Use API schema `components` for reusable HTTP shapes:
+
+```yaml
+# schema/bookstore/shared/enums.yml
+components:
+  schemas:
+    BookFormat:
+      type: string
+      enum: [hardcover, paperback, ebook]
+```
+
+## async-only reuse
+
+If the repo only has async schema sources, keep reusable message payload schemas and
+enums close to the messaging roots or under `schema/shared/` when several
+message families share the same meaning.
+
+```text
+schema/
+  shared/
+    message-enums.yml
+  bookstore/
+    bookstore.async.yml
+    messages/
+      book-commands.yml
+      book-events.yml
+    models/
+      books.yml
+      enums.yml
+```
+
+```yaml
+# schema/bookstore/models/enums.yml
+BookFormat:
+  type: string
+  enum: [hardcover, paperback, ebook]
+```
+
+## API + async shared components
+
+When one product capability has both HTTP and messaging contracts, keep protocol
+entrypoints separate and share only business schemas.
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml
+    bookstore.async.yml
+    paths/books.yml
+    messages/books.yml
+    models/enums.yml
+    models/books.yml
+```
+
+Good shared fragment:
+
+```yaml
+# schema/bookstore/models/enums.yml
+BookFormat:
+  type: string
+  enum: [hardcover, paperback, ebook]
+
+# schema/bookstore/models/books.yml
+BookSlug:
+  type: string
+  minLength: 1
+  maxLength: 120
+  pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+
+PaginationMeta:
+  $ref: ../../shared/common.yml#/components/schemas/PaginationMeta
+```
+
+API schema can use it through path and response fragments:
+
+```yaml
+# schema/bookstore/paths/books.yml
+parameters:
+  - name: bookSlug
+    in: path
+    required: true
+    schema:
+      $ref: ../models/books.yml#/BookSlug
+get:
+  operationId: getBook
+  responses:
+    "200":
+      description: Book detail.
+      content:
+        application/json:
+          schema:
+            $ref: ../models/books.yml#/Book
+```
+
+async schema can use the same payload schema from a message fragment:
+
+```yaml
+# schema/bookstore/messages/books.yml
+messages:
+  GetBookQuery:
+    payload:
+      $ref: ../models/books.yml#/GetBookQuery
+  BookReply:
+    payload:
+      $ref: ../models/books.yml#/Book
+```
+
+Keep protocol-specific pieces out of `models/`:
+
+- API schema paths, parameters, request bodies, responses → `paths/` or
+  `components/`.
+- async schema channels, operations, messages → `messages/`.
+- Payload objects, enums, scalars, and reusable business shapes → `models/`.
+- Share enums through `models/enums.yml` when API schema and async schema use the same
+  vocabulary and values.
+
+This keeps API contracts, async messages, and generated models aligned without
+making either protocol depend on the other's metadata.
+
+## Kontract sets for reusable map fragments
+
+Use `kontract.sets` when repeated YAML maps make the source noisy but the
+reusable concept is not a standalone schema. `$sets` can apply reusable maps in
+responses, parameters, schema properties, headers, request bodies, async
+operations, messages, payload schemas, or any other mapping.
+
+```yaml
+# schema/bookings/shared/components.yml
+kontract:
+  sets:
+    StandardErrors:
+      "400":
+        $ref: '#/components/responses/BadRequest'
+      "401":
+        $ref: '#/components/responses/Unauthorized'
+      "403":
+        $ref: '#/components/responses/Forbidden'
+      "404":
+        $ref: '#/components/responses/NotFound'
+      "500":
+        $ref: '#/components/responses/InternalServerError'
+    AuditedFields:
+      createdAt:
+        type: string
+        format: date-time
+      updatedAt:
+        type: string
+        format: date-time
+components:
+  responses:
+    BadRequest:
+      description: Bad request.
+    Unauthorized:
+      description: Unauthorized.
+    Forbidden:
+      description: Forbidden.
+    NotFound:
+      description: Not found.
+    InternalServerError:
+      description: Internal server error.
+```
+
+```yaml
+# schema/bookings/public.api.yml
+api: 3.0.3
+paths:
+  /bookings:
+    post:
+      responses:
+        $sets:
+          - $ref: ./shared/components.yml#/kontract/sets/StandardErrors
+        "201":
+          description: Booking created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateBookingResponse'
+components:
+  schemas:
+    Booking:
+      type: object
+      properties:
+        $sets:
+          - $ref: ./shared/components.yml#/kontract/sets/AuditedFields
+        id:
+          type: string
+```
+
+Set rules:
+
+- `$sets` merges maps only; it does not concatenate arrays.
+- Local keys override set keys.
+- Multiple sets that define the same key must use identical values.
+- Kontract rebases copied `$ref` values when a set comes from another file.
+- Normalized files passed to validators and generators do not contain
+  `kontract` or `$sets`.
+
+## Response envelopes
+
+If every endpoint repeats the same envelope fields, do not retype them in every
+schema. Put the shared part in a component and compose concrete responses with
+`allOf`.
+
+```yaml
+# schema/shared/common.yml
+components:
+  schemas:
+    SuccessResponseBase:
+      type: object
+      required: [success, timestamp, path]
+      properties:
+        success:
+          type: boolean
+        timestamp:
+          type: string
+          format: date-time
+        path:
+          type: string
+        message:
+          type: string
+```
+
+```yaml
+# schema/recipes/catalog.api.yml
+components:
+  schemas:
+    RecipesFindOneResponse:
+      allOf:
+        - $ref: ../shared/common.yml#/components/schemas/SuccessResponseBase
+        - type: object
+          required: [data]
+          properties:
+            data:
+              $ref: '#/components/schemas/RecipeResponse'
+```
+
+Use the same pattern for paginated responses:
+
+```yaml
+components:
+  schemas:
+    RecipesFindAllResponse:
+      allOf:
+        - $ref: ../shared/common.yml#/components/schemas/SuccessResponseBase
+        - type: object
+          required: [data]
+          properties:
+            data:
+              type: array
+              items:
+                $ref: '#/components/schemas/RecipeResponse'
+            meta:
+              $ref: ../shared/common.yml#/components/schemas/PaginationMeta
+```
+
+Kontract supports object `allOf` composition by flattening supported object refs
+and inline object parts. Today this mainly reduces YAML duplication and contract
+semantic drift. It may still emit concrete generated DTO/model properties per
+response until the generator grows preserved composition or shared-output
+emission.
+
+## Schedules and repeated nested objects
+
+If several features define the same day-of-week schedule or time-slot object,
+share the object definitions instead of duplicating each day shape.
+
+```yaml
+# schema/shared/scheduling.yml
+components:
+  schemas:
+    WeeklyTimeSlot:
+      type: object
+      required: [from, to]
+      properties:
+        from:
+          type: string
+          pattern: '^(0[6-9]|1\d|2[0-3]):[0-5]\d$'
+        to:
+          type: string
+          pattern: '^(0[6-9]|1\d|2[0-3]):[0-5]\d$'
+    WeeklySchedule:
+      type: object
+      properties:
+        sunday:
+          type: array
+          items:
+            $ref: '#/components/schemas/WeeklyTimeSlot'
+        monday:
+          type: array
+          items:
+            $ref: '#/components/schemas/WeeklyTimeSlot'
+```
+
+Then service-specific schedules can reference or compose those shared pieces.
+
+## Review checklist
+
+After writing or updating any `*.api.yml` or `*.async.yml` file, review
+the spec before running generation. Actively look for these smells:
+
+- the same `success/timestamp/path/message` fields repeated in many response
+  schemas;
+- identical pagination `meta` objects or `PaginationMeta` definitions copied
+  across services instead of referencing a shared component;
+- many `id` parameters declared inline instead of referencing a shared
+  parameter;
+- inline UUID, date, date-time, URL, slug, or enum-like scalar constraints that
+  already exist in a shared component;
+- identical regex patterns copied into multiple schemas;
+- repeated day-of-week schedule structures;
+- error response schemas or problem-details bodies copied instead of referencing
+  shared responses;
+- event envelopes or async schema reply wrappers copied with the same product
+  meaning;
+- generated diffs adding many near-identical DTO/model files after a small API
+  change.
+
+When you see a smell, propose a shared component before generating.
+
+## When not to share
+
+Do not share only because two shapes currently look alike. Keep separate
+components when:
+
+- endpoints have different validation rules or lifecycle/backwards-compatibility
+  needs;
+- a request DTO and response DTO intentionally differ, even if fields overlap;
+- names would become vague (`CommonThing`, `BaseData`, `GenericConfig`);
+- the reusable name would hide a real product term, such as using `Collection`
+  when collections are a product concept;
+- sharing would force unrelated teams or product areas to coordinate every
+  future change.
+
+A good shared component has a clear product meaning and a stable owner.
+
+## Safe workflow
+
+1. Keep new schemas local to the root or surface that owns them.
+2. When reuse appears inside one capability, move the repeated shape into that
+   capability's `shared/` folder and replace duplicates with `$ref`.
+3. When reuse appears across capabilities, promote the shape to
+   `schema/shared/` and update `$ref` links deliberately.
+4. Use supported `allOf` object composition when a concrete response extends a
+   shared base.
+5. Run `sumr kontract validate`.
+6. Run a scoped generation first, for example:
+
+```bash
+sumr kontract generate --source api --target backend --specific recipes/catalog
+```
+
+7. Review both the spec diff and generated diff. If generated output changed in
+   unrelated product areas, stop and investigate before committing.