Kontract

Design profile

Choose how examples should look for API contracts, async contracts, and schema folders. The profile guides docs and AI assistants; it does not change generated code or application architecture.

Set it, then change it safely

Store the profile in sumr.yaml.

Use sumr kontract init for first-time setup, thensumr kontract config to view or update profile values later without hand-editing YAML. Setup also adds VS Code icons for `.api.yml` and `.async.yml` schema files.

terminal

$sumr kontract init --api-style pragmatic-rest --async-style command-event --schema-layout-style by-product-capability# choose all profile axes during setup$sumr kontract config --api-style rpc-action --schema-layout-style by-workflow# change selected axes later

API styles

Pick the path and component style that matches the API schema surface.

Style	Choose this when	Sample path	Sample names
`pragmatic-rest`	Use for predictable REST without strict methodology overhead.	/v1/orders/{orderId}/items	Order, CreateOrderBody
`resource-oriented`	Use when the API follows resource hierarchy and standard methods closely.	/v1/publishers/{publisherId}/books/{bookId}	Book, ListBooksResponse
`json-api`	Use when clients expect JSON:API documents, relationships, and sparse fields.	/articles/1/relationships/comments	ArticleResource, ArticleRelationship
`odata`	Use when consumers need OData query, filter, and metadata conventions.	/Products?$filter=price gt 10	ProductEntity, ProductCollection
`rpc-action`	Use when operations are action-first and not naturally modeled as CRUD.	/v1/reports:generate	GenerateReportRequest, GenerateReportResult
`graphql-http`	Use when API requests carry GraphQL operations.	/graphql	GetOrderVariables
`hypermedia-rest`	Use when clients navigate links and state transitions from representations.	/v1/orders/{orderId} with links.cancel	OrderLinks, OrderRepresentation
`webhook-callback`	Use when the contract documents callbacks or externally delivered HTTP events.	/webhooks/order-created	OrderCreatedWebhook, WebhookAck
`mixed`	Use when multiple API styles are intentional and documented by surface.	/v1/orders and /graphql	Names match each surface

Async schema styles

Pick the channel and message style that matches the async contract.

Style	Choose this when	Sample channel	Sample names
`command-event`	Use when commands and events are separate contract families.	cmd.billing.invoices.create, evt.billing.invoices.created	CreateInvoiceCommand, InvoiceCreatedEvent
`event-driven`	Use when services primarily publish facts that subscribers react to.	billing.invoice.created	InvoiceCreated
`request-reply`	Use for query/reply or command/reply messaging interactions.	qry.catalog.products.get	GetProductQuery, ProductReply
`cloud-events`	Use when events must follow CloudEvents envelope semantics.	com.example.invoice.created	InvoiceCreatedCloudEvent
`mixed`	Use when multiple messaging styles are intentional and documented by family.	cmd., evt., and CloudEvents topics	Names match each family

Schema source styles

Pick how schema files and folders should be grouped after choosing the schema type: API schema-only, async schema-only, or both with shared neutral components such as enums.

Style	Choose this when	Sample layout
`by-product-capability`	Use when a product capability owns the selected schema roots. API schema-only repos, async schema-only repos, and repos that use both should show different examples.	API schema-only: schema/recipes/recipes.api.yml; both: schema/recipes/{recipes.api.yml, recipes.async.yml, models/enums.yml}
`by-api-surface`	Use when public, partner, admin, internal, or messaging surfaces release separately.	API schema-only: schema/public.api.yml; async schema-only: schema/internal-events.async.yml
`by-service-owner`	Use when teams generate contracts by deployable service ownership.	schema/catalog-service/catalog.api.yml or schema/notification-service/notifications.async.yml
`by-resource-area`	Use when specs are easiest to review by stable resource area. Do not nest resource areas under product capabilities unless style is mixed.	schema/books/books.api.yml, schema/authors/authors.api.yml
`by-workflow`	Use when one workflow spans several resources and needs one contract owner.	schema/checkout/checkout.api.yml or schema/fulfillment/fulfillment.async.yml
`by-message-family`	Use when messaging files are owned by command, event, query, or reply family. This is normally async schema-only.	schema/events/book-events.async.yml
`mixed`	Use when legacy or multi-team layouts intentionally differ by folder. Document each folder's style and schema type.	schema/public.api.yml plus schema/events/book-events.async.yml plus documented mixed folders