Kontract

Set guidance profile

Choose the example style Kontract should use when it explains specs to humans and AI assistants. The command updates sumr.yaml; generated contracts still come from the API schemas, async schemas, or shared schema files you author.

Preview before choosing

Guidance, not output

Pick the style that matches how your team wants source specs to read. After the profile is saved, Kontract examples and AI guidance point authors to patterns like the ones below. To produce code or SDKs, edit the schema source, then run validation and generation.

terminal

$sumr kontract config# show current profile$sumr kontract config --api-style rpc-action --async-style request-reply --schema-layout-style by-workflow# change the examples Kontract recommends$sumr kontract validate && sumr kontract generate# generate from specs

API schema examples

Use --api-style to choose the API schema path and component examples Kontract should recommend.

Saved in this browser.

pragmatic-rest

Use resource paths and conventional operations without forcing one strict REST school.

api: 3.1.0
paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get order
      responses:
        "200":
          description: Order returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
components:
  schemas:
    Order:
      type: object
      required: [id, status]

Async schema style examples

Use --async-style to choose how async channels and messages should be named and grouped.

Saved in this browser.

command-event

Separate imperative commands from fact events and name the reply path explicitly.

async: 3.0.0
channels:
  createInvoice:
    address: cmd.billing.invoices.create
    messages:
      createInvoiceCommand:
        $ref: "#/components/messages/CreateInvoiceCommand"
  invoiceCreated:
    address: evt.billing.invoices.created
    messages:
      invoiceCreatedEvent:
        $ref: "#/components/messages/InvoiceCreatedEvent"
operations:
  createInvoice:
    summary: Create invoice
    description: Requests creation of an invoice for the supplied billing data.
    action: receive
    channel:
      $ref: "#/channels/createInvoice"
  publishInvoiceCreated:
    summary: Publish invoice created
    action: send
    channel:
      $ref: "#/channels/invoiceCreated"

Schema type examples

Choose the schema type first: API schema-only, async schema-only, or both with shared neutral components such as enums.

Saved in this browser.

api-only

Use this when the repo only defines API contracts. Keep paths, parameters, responses, and components in API schema layers.

schema/
  shared/
    errors.yml
    pagination.yml
  bookstore/
    bookstore.api.yml
    shared.yml

# No *.async.yml, messages/, or channel examples.

Reusable schema set examples

Use kontract.sets and $sets to reuse map fragments anywhere a mapping exists. Prefer local ownership first, then promote only truly shared pieces into shared/.

Saved in this browser.

standard-errors

Apply a shared response map, then define the operation-specific success response locally.

kontract:
  sets:
    StandardErrors:
      "400":
        $ref: ../shared/common.yml#/components/responses/BadRequest
      "401":
        $ref: ../shared/common.yml#/components/responses/Unauthorized
      "404":
        $ref: ../shared/common.yml#/components/responses/NotFound
      "500":
        $ref: ../shared/common.yml#/components/responses/InternalServerError
paths:
  /bookings/{bookingId}/payments:
    post:
      operationId: createBookingPayment
      summary: Create booking payment
      responses:
        $sets: [StandardErrors]
        "201":
          description: Payment created

Schema layout examples

Use --schema-layout-style after the schema type is clear. Show only the API or async schema roots the repo actually has.

Saved in this browser.

by-product-capability

Group the selected schema roots around the product capability that owns the behavior.

schema/
  recipes/
    # API schema-only
    recipes.api.yml

  recipes-messaging/
    # async schema-only capability
    recipes.async.yml
    messages/
      recipe-events.yml

  bookstore/
    # Both schema types, separate layers
    bookstore.api.yml
    bookstore.async.yml
    paths/
      books.yml
    messages/
      books.yml
    models/
      enums.yml