One .proto, three wire formats. Built for humans and machines.

// Schema-pinned to infra.v1.ServerConfig
@type infra.v1.ServerConfig

hostname = "web-01.prod.example.com"
port     = 8443
enabled  = true
status   = STATUS_SERVING

created_at = 2024-01-15T10:30:00Z
timeout    = 30s

tls {
  cert_file = "/etc/ssl/cert.pem"
  key_file  = "/etc/ssl/key.pem"
  verify    = true
}

tags = ["production", "us-east", "frontend"]

labels = {
  env: "production"
  team: "platform"
  "hello world": "quoted keys supported"
}

syntax = "proto3";
package infra.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

message ServerConfig {
  string hostname = 1;
  int32 port = 2;
  bool enabled = 3;
  Status status = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Duration timeout = 6;
  TLS tls = 7;
  repeated string tags = 8;
  map<string, string> labels = 9;
}

enum Status {
  STATUS_UNSPECIFIED = 0;
  STATUS_SERVING = 1;
}

message TLS {
  string cert_file = 1;
  string key_file = 2;
  bool verify = 3;
}

endpoints = [
  {
    path   = "/api/v1/users"
    method = GET
  }
  {
    path   = "/health"
    method = GET
  }
]

error_codes = {
  404: "Not Found"
  500: "Internal Error"
}

nullable_name = "present"

message ServerConfig {
  // ... fields from previous example ...
  repeated Endpoint endpoints = 10;
  map<int32, string> error_codes = 11;
  optional string nullable_name = 12;
}

message Endpoint {
  string path = 1;
  Method method = 2;
}

enum Method {
  METHOD_UNSPECIFIED = 0;
  GET = 1;
  POST = 2;
  PUT = 3;
  DELETE = 4;
}

event_id = "evt-456"

user {
  user_id = "u-123"
  login {
    ip  = "192.168.1.1"
    mfa = true
  }
}

message Event {
  string event_id = 1;
  User user = 2;
}

message User {
  string user_id = 1;
  oneof action {
    Login login = 10;
    Logout logout = 11;
  }
}

message Login {
  string ip = 1;
  bool mfa = 2;
}

message Logout {
  string reason = 1;
}

Field options (pxf.required) = true and (pxf.default) = "…" travel with the schema. A decoder rejects any document that omits a required field, and fills in the literal default when an annotated field is absent. Defaults apply to absent fields only, never to fields explicitly set to null or to the proto3 zero value.

@type infra.v1.ServerConfig

hostname = "web-01.prod.example.com"
region   = "us-east-1"

# port, enabled, log_level are all omitted.
# The decoder fills them with the schema's defaults:
#   port      = 8080
#   enabled   = true
#   log_level = "info"
#
# Drop the `region =` line and the same decoder rejects
# the document: required field "region" is missing.

syntax = "proto3";
package infra.v1;

import "pxf/annotations.proto";

message ServerConfig {
  string hostname  = 1 [(pxf.required) = true];
  string region    = 2 [(pxf.required) = true];

  int32  port      = 3 [(pxf.default)  = "8080"];
  bool   enabled   = 4 [(pxf.default)  = "true"];
  string log_level = 5 [(pxf.default)  = "\"info\""];
}

# trades.pxf carries an @proto schema header + @dataset rows.
# No -p flag needed; the schema travels with the data.

# Count rows where the symbol is AAPL:
pxf query 'pxf_directive("dataset")[0].rows
            | map(select(.symbol == "AAPL"))
            | length' trades.pxf

# Build a typed object from a different file and emit valid PXF:
pxf query 'pxf_proto("trades.v1.Trade";
            { symbol: .ticker, price: .last, qty: .size })' raw.json

# Adapt CSV / JSON / YAML on the way in; output is always PXF:
pxf query '.endpoints[0].path' config.yaml

# Count query:
value = 2

# pxf_proto constructor — emits a typed PXF document:
@type trades.v1.Trade
symbol = "AAPL"
price  = 188.42
qty    = 100

# YAML field extraction:
value = "/api/v1/users"

// Self-describing PXF: the @proto header lets readers parse the
// @dataset rows without a separate .proto file on disk.
@proto trades.v1.Trade {
  string symbol = 1;
  double price  = 2;
  int64  qty    = 3;
}
@dataset trades.v1.Trade ( symbol, price, qty )
( "AAPL", 188.42, 100 )
( "MSFT", 415.10,  50 )
( "AAPL", 188.55,  75 )

{
  "ticker": "AAPL",
  "last":   188.42,
  "size":   100,
  "venue":  "NASDAQ",
  "flags":  ["odd_lot"]
}

endpoints:
  - path: /api/v1/users
    method: GET
    timeout_ms: 5000
  - path: /api/v1/orders
    method: POST
    timeout_ms: 10000
  - path: /health
    method: GET
    timeout_ms: 1000