Kinds and components

A kind is an abstract category with typed properties. A component is a concrete product implementing exactly one kind. Nothing in either of them is display text: names and descriptions live in locales/, keyed by id, so the documents stay language-neutral.

Kind

A kind answers "what is a queue?" — not "which queue".

1schemaVersion: "1"
2type: "kind"
3id: "queue"
4category: "messaging"
5properties:
6  delivery:
7    type: "enum"
8    values: ["at-most-once", "at-least-once", "exactly-once"]
9    required: true
10  ordering:
11    type: "enum"
12    values: ["none", "per-key", "global"]
13    default: "none"
14  deadLetterQueue:
15    type: "boolean"
16    default: false

external is for services outside your control, such as a payment provider. custom holds only the custom kind, the untyped escape hatch.

Property definitions

A property with neither default nor required is optional and may be absent. That absence is usually deliberate: it is what lets a rule catch it.

Component

A component answers "what is SQS?" — one file per product.

1schemaVersion: "1"
2type: "component"
3id: "sqs"
4kind: "queue"
5provider: "aws"
6docs: "https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html"
7defaults:
8  managed: true
9  delivery: "at-least-once"
10  ordering: "none"
11  replay: false
12  retentionDays: 4
13properties:
14  fifo:
15    type: "boolean"
16    default: false
17  visibilityTimeoutSeconds:
18    type: "integer"
19    default: 30

A defaults entry states the product's actual default behaviour, not a recommended configuration. SQS really does retain for four days; that is why the number is there.

Providers

Provider is ownership, not hosting. postgres is default even when it runs on RDS; aurora is aws because Amazon owns it. default covers open source, in-house generic components, and independent SaaS such as Stripe or Datadog.

A cloud provider's managed offering of an open-source product is its own component, not a flag on the original, because it is the resource a designer actually places and it carries its own defaults: backup retention, zone redundancy, encryption.

Property resolution order

For a node in a design, the effective value of a property is the first of these that exists:

1. The node's own props
2. The component's defaults
3. The property definition's default — on the kind, or on the component for a component-specific property
4. Absent

Absent is a real answer, not an error. Rules test for it with exists: false.

1nodes:
2  - id: "orders-queue"
3    component: "sqs"
4    props: { deadLetterQueue: true }

deadLetterQueue resolves to true from the node. delivery resolves to "at-least-once" from the component's defaults. ordering resolves to "none", which the component happens to pin to the same value the kind defaults to. retentionDays is 4, from the component. backoff has no default anywhere and no node value, so it is absent, and retry-without-backoff can say so.

A node may only set properties that exist on its component's kind or on the component itself. Setting an unknown property is a structural error.

Which kinds exist

Every kind has a reference page listing its properties, the rules that read them, and every component that implements it, grouped by provider.