Specification
Complete FARP protocol specification reference
This page provides a condensed reference of the FARP protocol specification. For the full specification, see SPECIFICATION.md.
Protocol Overview
FARP defines a standard format for services to advertise their API schemas, health information, and capabilities to API gateways and service meshes. The protocol consists of:
- Schema Manifest — JSON document describing a service instance's API surface
- Schema Providers — Components that generate schemas from application code
- Schema Registry — Storage abstraction for manifests and schemas
- Schema Merger — Utilities for composing multiple schemas into unified documentation
Registration Flow
1. Service starts
2. Schema providers generate schemas (OpenAPI, gRPC, etc.)
3. Service creates a SchemaManifest
4. Service registers the manifest with a discovery backend
5. Gateway watches for manifest changes
6. Gateway fetches schemas and auto-configures routes
7. On schema update: service updates manifest, gateway reconfigures
8. On shutdown: service deregisters manifestCore Data Structures
SchemaManifest Fields
| Field | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Protocol version (semver) |
service_name | string | Yes | Logical service name |
service_version | string | Yes | Service version (semver) |
instance_id | string | Yes | Unique instance identifier |
instance | InstanceMetadata | No | Instance metadata |
schemas | SchemaDescriptor[] | Yes | API schemas |
capabilities | string[] | No | Supported protocols |
endpoints | SchemaEndpoints | Yes | Introspection URLs |
routing | RoutingConfig | No | Gateway routing config |
auth | AuthConfig | No | Authentication config |
webhook | WebhookConfig | No | Bidirectional communication |
hints | ServiceHints | No | Operational hints |
updated_at | int64 | Yes | Unix timestamp |
checksum | string | Yes | SHA256 of all schemas |
Schema Types
| Type | Constant | Supported Spec Versions |
|---|---|---|
| OpenAPI | openapi | 3.0.x, 3.1.x |
| AsyncAPI | asyncapi | 2.x, 3.0.x |
| gRPC | grpc | proto2, proto3 |
| GraphQL | graphql | 2021, June 2018 |
| oRPC | orpc | 1.0.0 |
| Thrift | thrift | 0.19.x |
| Avro | avro | 1.11.x |
| Custom | custom | — |
Location Types
| Type | Behavior |
|---|---|
inline | Schema embedded directly in manifest |
http | Schema fetched via HTTP GET |
registry | Schema stored in registry KV store |
Mount Strategies
| Strategy | URL Pattern |
|---|---|
root | /path |
instance | /{instance_id}/path |
service | /{service_name}/path |
versioned | /{service_name}/{version}/path |
custom | /{base_path}/path |
subdomain | {subdomain}.gateway.com/path |
Interfaces
SchemaProvider
Type() SchemaType
Generate(ctx, app) (any, error)
Validate(schema) error
Hash(schema) (string, error)
Serialize(schema) ([]byte, error)
Endpoint() string
SpecVersion() string
ContentType() stringSchemaRegistry
RegisterManifest(ctx, manifest) error
GetManifest(ctx, instanceID) (*SchemaManifest, error)
UpdateManifest(ctx, manifest) error
DeleteManifest(ctx, instanceID) error
ListManifests(ctx, serviceName) ([]*SchemaManifest, error)
PublishSchema(ctx, path, schema) error
FetchSchema(ctx, path) (any, error)
DeleteSchema(ctx, path) error
WatchManifests(ctx, serviceName, handler) error
WatchSchemas(ctx, path, handler) error
Close() error
Health(ctx) errorStorageBackend
Put(ctx, key, value) error
Get(ctx, key) ([]byte, error)
Delete(ctx, key) error
List(ctx, prefix) ([]string, error)
Watch(ctx, prefix) (<-chan StorageEvent, error)
Close() errorService Hints
Non-binding operational hints for gateways:
type ServiceHints struct {
PreferredLoadBalancer LoadBalancerType `json:"preferred_lb,omitempty"`
MaxConcurrency int `json:"max_concurrency,omitempty"`
RateLimit *RateLimitHint `json:"rate_limit,omitempty"`
CircuitBreaker *CircuitBreakerHint `json:"circuit_breaker,omitempty"`
Timeout *TimeoutHint `json:"timeout,omitempty"`
Retry *RetryHint `json:"retry,omitempty"`
Caching *CachingHint `json:"caching,omitempty"`
}Service hints are advisory. Gateways may override them based on their own policies.
Error Types
| Error | Description |
|---|---|
ErrManifestNotFound | Manifest not in registry |
ErrSchemaNotFound | Schema not in registry |
ErrInvalidManifest | Manifest fails validation |
ErrInvalidSchema | Schema fails validation |
ErrInvalidLocation | Unknown location type |
ErrSchemaToLarge | Schema exceeds size limit |
ErrRegistryUnavailable | Registry backend unreachable |
ErrProviderNotFound | Unknown schema provider |
How is this guide?