Referência do schema YAML

Gerada a partir de schema/pipevine.schema.json, que por sua vez é gerado por reflection sobre Pipevine.Model (Pipevine.Cli's comando schema) — nenhum dos dois é escrito à mão. Para uma referência com descrição por campo, veja Configuração YAML; para a política de versionamento do schema, veja Versionamento.

raiz do documento

Campo	Tipo	Obrigatório	Descrição
apiVersion	string	sim	The document's apiVersion, e.g. pipevine.dev/v1 — versioned since day one so the schema can evolve without breaking existing documents.
kind	string	sim	The document's kind. Always Application today.
metadata	objeto (ver seção abaixo)	sim	The document's metadata block: name, version, and optional description.
spec	objeto (ver seção abaixo)	sim	The document's spec block: everything that defines what the application actually does.

raiz do documento → metadata

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The application's identifier, e.g. orders.
version	string	sim	The application's version string, e.g. 1.0.0. Free-form — not tied to AppDefinition.ApiVersion.
description	string	não	An optional human-readable description of the application.

raiz do documento → spec

Campo	Tipo	Obrigatório	Descrição
type	api | consumer	sim	Whether this application is an HTTP API or a message consumer.
auth	objeto (ver seção abaixo)	não	The default inbound auth scheme and the catalog of schemes routes/integrations can reference by id.
routes	lista de objeto (ver seção abaixo)	não	The HTTP routes, populated when Type is AppKind.Api.
consumers	lista de objeto (ver seção abaixo)	não	The message consumers, populated when Type is AppKind.Consumer.
dataSources	lista de objeto (ver seção abaixo)	não	The relational/document data sources a db.* step or an entity can reference by id.
caches	lista de objeto (ver seção abaixo)	não	The cache resources a cache.* step can reference by id.
brokers	lista de objeto (ver seção abaixo)	não	The message brokers a consumer or a publish step's event can reference by id.
storages	lista de objeto (ver seção abaixo)	não	The blob storage resources a storage.* step can reference by id.
entities	lista de objeto (ver seção abaixo)	não	The persisted shapes db.* steps read and write, each bound to one of SpecDefinition.DataSources.
events	lista de objeto (ver seção abaixo)	não	The message shapes a publish step can emit, and what the AsyncAPI output documents.
integrations	lista de objeto (ver seção abaixo)	não	The outbound HTTP/gRPC dependencies an http.call/grpc.call step can reference by id.
schemas	lista de objeto (ver seção abaixo)	não	The named request/response shapes routes reference for typed contract generation and OpenAPI.

raiz do documento → spec → auth

Campo	Tipo	Obrigatório	Descrição
default	objeto (ver seção abaixo)	não	The auth scheme applied to any route/consumer that doesn't declare its own auth: and isn't anonymous: true.
schemes	lista de objeto (ver seção abaixo)	não	The catalog of auth schemes available to be referenced by id.

raiz do documento → spec → auth → default

Campo	Tipo	Obrigatório	Descrição
scheme	string	sim	The scheme kind at the call site, e.g. jwt — informational, not authoritative.
ref	string	sim	The id of the entry in AuthDefinition.Schemes this reference resolves to.

raiz do documento → spec → auth → schemes

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The identifier other parts of the YAML reference via ref:.
scheme	string	sim	The discriminator selecting which IInboundAuthScheme handles this entry, e.g. jwt.

raiz do documento → spec → routes

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The route's identifier, used in logs/traces.
method	string	sim	The HTTP method, e.g. POST.
path	string	sim	The route template, e.g. /orders/{orderId}.
summary	string	não	A short human-readable summary, carried into the OpenAPI output.
tags	lista de string	não	OpenAPI tags for grouping this route in generated documentation.
request	objeto (ver seção abaixo)	não	What this route accepts: headers, query parameters, and the declared body shape.
auth	objeto (ver seção abaixo)	não	The auth scheme applied to this route. null falls back to spec.auth.default unless Anonymous.
anonymous	boolean	não	When true, this route skips authentication entirely, regardless of spec.auth.default.
authorize	objeto (ver seção abaixo)	não	Additional authorization checks applied after authentication.
transaction	none | required	não	Whether the pipeline runs inside a shared, ambient data transaction.
cache	objeto (ver seção abaixo)	não	Cache-aside behavior for this route's response.
pipeline	lista de objeto (ver seção abaixo)	não	The steps run to handle a request to this route.
response	objeto (ver seção abaixo)	não	How the pipeline's outcome maps to an HTTP response.
errors	lista de objeto (ver seção abaixo)	não	How specific fail step codes map to HTTP status/title.

raiz do documento → spec → routes → request

Campo	Tipo	Obrigatório	Descrição
body	objeto (ver seção abaixo)	não	The declared shape/content type of the request body, for OpenAPI. Doesn't itself validate — see the pipeline's validate step.
headers	lista de objeto (ver seção abaixo)	não	The headers this route expects.
query	lista de objeto (ver seção abaixo)	não	The query parameters this route expects.

raiz do documento → spec → routes → request → body

Campo	Tipo	Obrigatório	Descrição
schema	string	não	The name of a SchemaDefinition describing the body shape. Optional: a route can leave the request body untyped.
contentType	string	não	The expected media type, e.g. application/json. Carried into the OpenAPI output.

raiz do documento → spec → routes → request → headers

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The header name.
required	boolean	não	Whether a missing header is rejected with 400 before the pipeline runs.
description	string	não	A human-readable description, carried into the OpenAPI output.

raiz do documento → spec → routes → request → query

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The query parameter name.
type	string	não	The parameter's primitive type, e.g. boolean, string. Guides both binding and the OpenAPI schema.
required	boolean	não	Whether a missing parameter is rejected with 400 before the pipeline runs.

raiz do documento → spec → routes → auth

Campo	Tipo	Obrigatório	Descrição
scheme	string	sim	The scheme kind at the call site, e.g. jwt — informational, not authoritative.
ref	string	sim	The id of the entry in AuthDefinition.Schemes this reference resolves to.

raiz do documento → spec → routes → authorize

Campo	Tipo	Obrigatório	Descrição
scopes	lista de string	não	The OAuth-style scopes the principal must carry.
roles	lista de string	não	The roles the principal must carry.
claims	objeto (ver seção abaixo)	não	The exact claim values the principal must carry.
expr	string	não	An optional JSONata boolean policy expression evaluated over the pipeline's input, for checks the other fields can't express.

raiz do documento → spec → routes → cache

Campo	Tipo	Obrigatório	Descrição
key	string	não	A JSONata expression producing the cache key.
ttl	string	não	How long a cached response is valid, e.g. 5m.
tags	lista de string	não	Tags a cache.invalidate step elsewhere can use to evict this entry.
bypassWhen	string	não	A JSONata boolean expression; when true, the cache is bypassed for this request.

raiz do documento → spec → routes → pipeline

Campo	Tipo	Obrigatório	Descrição
type	string	sim	The step key, e.g. db.persist — resolves which IStepFactory builds this step. Unknown at build time, this fails the build.
id	string	não	Optional. When set, the step's result is published at steps..result, visible to expressions later in the same scope.
when	string	não	Optional JSONata boolean expression. The step only executes when it evaluates truthy — cheaper than wrapping the step in a branch.

raiz do documento → spec → routes → response

Campo	Tipo	Obrigatório	Descrição
status	integer	não	The HTTP status code returned when the pipeline completes/short-circuits successfully.
headers	objeto (ver seção abaixo)	não	Response headers, each computed by its own JSONata expression.
body	string	não	A JSONata expression producing the response body from the pipeline state.
schema	string	não	The name of a SchemaDefinition describing Body's shape. Optional: a route can leave the response body untyped.

raiz do documento → spec → routes → errors

Campo	Tipo	Obrigatório	Descrição
code	string	sim	The fail step's code this mapping applies to.
status	integer	não	The HTTP status code to return.
title	string	não	The ProblemDetails title. null falls back to a default.

raiz do documento → spec → consumers

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The consumer's identifier, used in logs/traces and as the idempotency scope.
source	string	sim	The id of the broker (spec.brokers) this consumer reads from.
queue	string	não	The RabbitMQ queue to consume from. Mutually exclusive with Topic.
topic	string	não	The Kafka topic to consume from. Mutually exclusive with Queue.
consumerGroup	string	não	The Kafka consumer group id, when Topic is set.
concurrency	integer	não	The number of messages processed concurrently. null uses the provider's default (usually 1).
prefetch	integer	não	The number of unacknowledged messages the broker may deliver ahead of processing.
retry	objeto (ver seção abaixo)	não	The retry policy applied when the pipeline fails for a message.
deadLetter	objeto (ver seção abaixo)	não	Where a message goes once Retry is exhausted.
idempotency	objeto (ver seção abaixo)	não	How duplicate deliveries of the same message are detected and skipped.
pipeline	lista de objeto (ver seção abaixo)	não	The steps run for each consumed message — the same step vocabulary an API route's pipeline uses.

raiz do documento → spec → consumers → retry

Campo	Tipo	Obrigatório	Descrição
attempts	integer	não	The maximum number of attempts, including the first.
backoff	objeto (ver seção abaixo)	não	The delay strategy between attempts.
on	lista de integer	não	The HTTP status codes that trigger a retry. Empty for a consumer retry, where every failure retries.

raiz do documento → spec → consumers → retry → backoff

Campo	Tipo	Obrigatório	Descrição
initial	string	não	The initial delay before the first retry, e.g. 1s. null uses the provider's default.
max	string	não	The maximum delay a retry can back off to, e.g. 30s.
jitter	boolean	não	Whether to randomize the delay to avoid synchronized retries across instances.

raiz do documento → spec → consumers → deadLetter

Campo	Tipo	Obrigatório	Descrição
queue	string	sim	The name of the dead-letter queue/topic.

raiz do documento → spec → consumers → idempotency

Campo	Tipo	Obrigatório	Descrição
key	string	sim	A JSONata expression producing the idempotency key from the consumed message.
store	string	não	The id of the data source or cache resource that persists seen keys. null uses the consumer's own data source.
ttl	string	não	How long a key is remembered before it can be reused, e.g. 24h.

raiz do documento → spec → consumers → pipeline

Campo	Tipo	Obrigatório	Descrição
type	string	sim	The step key, e.g. db.persist — resolves which IStepFactory builds this step. Unknown at build time, this fails the build.
id	string	não	Optional. When set, the step's result is published at steps..result, visible to expressions later in the same scope.
when	string	não	Optional JSONata boolean expression. The step only executes when it evaluates truthy — cheaper than wrapping the step in a branch.

raiz do documento → spec → dataSources

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The identifier entities and db.* steps reference by name.
provider	string	sim	The discriminator selecting which IDataProvider handles this entry, e.g. postgres.

raiz do documento → spec → caches

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The identifier cache.* steps and route-level cache: blocks reference by name.
provider	string	sim	The discriminator selecting which ICacheProvider handles this entry, e.g. redis.

raiz do documento → spec → brokers

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The identifier consumers and publish-step events reference via source:/broker:.
provider	string	sim	The discriminator selecting which IMessageProvider handles this entry, e.g. rabbitmq.

raiz do documento → spec → storages

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The identifier storage.* steps reference by name via their storage: field.
provider	string	sim	The discriminator selecting which IStorageProvider handles this entry, e.g. s3.

raiz do documento → spec → entities

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The entity's identifier, referenced by db.* steps via entity:.
table	string	sim	The underlying table name.
dataSource	string	sim	The id of the DataSourceDefinition this entity is persisted through.
key	string	sim	The name of the property that uniquely identifies a row, used by db.update/db.delete/upsert.
properties	lista de objeto (ver seção abaixo)	não	The entity's columns.
options	objeto (ver seção abaixo)	não	Free-form, provider-specific modeling that the core vocabulary has no universal name for — a partition key, clustering keys, a DynamoDB GSI, and similar (docs/features/bancos-nosql/tdd.md § "spec.entities[].options"). null when the entity declares no options:. The core never reads its fields; the provider targeted by EntityDefinition.DataSource validates them at build time, naming the entity and the unknown field when one doesn't apply — same free-node pattern as StepDefinition.Config.

raiz do documento → spec → entities → properties

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The property name, and the column name in the underlying store.
type	string	sim	The primitive type token, e.g. uuid, string, decimal, timestamptz, jsonb.
precision	integer	não	For decimal: total number of digits. null for other types.
scale	integer	não	For decimal: digits after the decimal point. null for other types.
index	boolean	não	Whether the provider should create an index on this column.

raiz do documento → spec → events

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The event's identifier, referenced by publish steps via event:.
schema	string	não	The name of a SchemaDefinition describing the payload shape, for AsyncAPI. Optional: an event can leave its payload untyped.
broker	string	sim	The id of the BrokerDefinition this event is published through.
topic	string	sim	The broker-native destination (Kafka topic or RabbitMQ routing key).
partitionKey	string	não	A JSONata expression producing the Kafka partition key. null for brokers without partitioning, or to let the provider default.
description	string	não	A human-readable description of the event, carried into the AsyncAPI output.

raiz do documento → spec → integrations

Campo	Tipo	Obrigatório	Descrição
id	string	sim	The integration's identifier, referenced by http.call/grpc.call steps via integration:.
kind	http | grpc	sim	Whether calls to this integration go over HTTP or gRPC.
baseUrl	string	sim	The base URL/address of the target service.
auth	objeto (ver seção abaixo)	não	The outbound auth scheme applied to every call, if any.
resilience	objeto (ver seção abaixo)	não	The resilience pipeline (timeout/retry/circuit-breaker/fallback/rate-limiter) applied to every call, unless a step overrides it.

raiz do documento → spec → integrations → auth

Campo	Tipo	Obrigatório	Descrição
scheme	string	sim	The scheme kind at the call site, e.g. jwt — informational, not authoritative.
ref	string	sim	The id of the entry in AuthDefinition.Schemes this reference resolves to.

raiz do documento → spec → integrations → resilience

Campo	Tipo	Obrigatório	Descrição
timeout	objeto (ver seção abaixo)	não	The timeout budget for a call.
retry	objeto (ver seção abaixo)	não	The retry policy for a failed call.
circuitBreaker	objeto (ver seção abaixo)	não	The circuit-breaker parameters.
fallback	objeto (ver seção abaixo)	não	What to return when the call still fails after the above.
rateLimiter	objeto (ver seção abaixo)	não	The outbound call rate limit.

raiz do documento → spec → integrations → resilience → timeout

Campo	Tipo	Obrigatório	Descrição
perAttempt	string	não	The maximum duration of a single attempt, e.g. 2s.
total	string	não	The maximum duration across all attempts (including retries), e.g. 8s.

raiz do documento → spec → integrations → resilience → retry

Campo	Tipo	Obrigatório	Descrição
attempts	integer	não	The maximum number of attempts, including the first.
backoff	objeto (ver seção abaixo)	não	The delay strategy between attempts.
on	lista de integer	não	The HTTP status codes that trigger a retry. Empty for a consumer retry, where every failure retries.

raiz do documento → spec → integrations → resilience → retry → backoff

Campo	Tipo	Obrigatório	Descrição
initial	string	não	The initial delay before the first retry, e.g. 1s. null uses the provider's default.
max	string	não	The maximum delay a retry can back off to, e.g. 30s.
jitter	boolean	não	Whether to randomize the delay to avoid synchronized retries across instances.

raiz do documento → spec → integrations → resilience → circuitBreaker

Campo	Tipo	Obrigatório	Descrição
failureRatio	number	não	The failure ratio, within CircuitBreakerDefinition.SamplingDuration, that trips the breaker (e.g. 0.5 for 50%).
samplingDuration	string	não	The rolling window over which CircuitBreakerDefinition.FailureRatio is measured, e.g. 30s.
minimumThroughput	integer	não	The minimum number of calls within CircuitBreakerDefinition.SamplingDuration before the breaker can trip — avoids tripping on a tiny sample.
breakDuration	string	não	How long the breaker stays open (rejecting calls) once tripped, e.g. 15s.

raiz do documento → spec → integrations → resilience → fallback

Campo	Tipo	Obrigatório	Descrição
expr	string	não	A JSONata expression producing the degraded result directly. Mutually exclusive with Pipeline.
pipeline	lista de objeto (ver seção abaixo)	não	A sub-pipeline run, in the caller's own pipeline context, to produce the degraded result. Mutually exclusive with Expr.

raiz do documento → spec → integrations → resilience → fallback → pipeline

Campo	Tipo	Obrigatório	Descrição
type	string	sim	The step key, e.g. db.persist — resolves which IStepFactory builds this step. Unknown at build time, this fails the build.
id	string	não	Optional. When set, the step's result is published at steps..result, visible to expressions later in the same scope.
when	string	não	Optional JSONata boolean expression. The step only executes when it evaluates truthy — cheaper than wrapping the step in a branch.

raiz do documento → spec → integrations → resilience → rateLimiter

Campo	Tipo	Obrigatório	Descrição
permitLimit	integer	não	The maximum number of concurrent calls.
window	string	não	The time window permits are replenished over, e.g. 1s. Used together with PermitLimit for a sliding/fixed window limiter.
queueLimit	integer	não	The maximum number of calls allowed to wait for a permit before being rejected.

raiz do documento → spec → schemas

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The schema's identifier, referenced by request.body.schema/response.schema and by other schemas for nesting.
properties	lista de objeto (ver seção abaixo)	não	The schema's properties.

raiz do documento → spec → schemas → properties

Campo	Tipo	Obrigatório	Descrição
name	string	sim	The property name.
type	string	sim	The type token — a primitive, an array suffixed with [], or another schema's name for nesting.
required	boolean	não	Whether this property must be present.