Protocol Buffers from a schema you can also read as text

Protobuf data means nothing without its .proto file. In NOVA the schema is optional and the data reads as text on its own. When you need Protobuf, @id(n) is the field number and nvf schema proto generates the .proto.

infrastructure.proto generated by nvf schema proto
syntax = "proto3";

package infrastructure.v1;

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

message Service {
  string id = 1;
  uint32 port = 3;
  uint32 replicas = 4;
  Status status = 5;
  google.protobuf.Timestamp deployed_at = 6;
}

message Status {
  oneof variant {
    google.protobuf.Empty active = 1;
    google.protobuf.Empty draining = 2;
    string failed = 3;
  }
}
infrastructure.novs the source
@schema infrastructure@1.0.0
@root Service

record Service:
  id: string @key @id(1)
  port: u16 @range(1..65535) @id(3)
  replicas: u16 @range(0..100) @id(4)
  status: Status @id(5) = !active
  deployed_at?: timestamp @id(6)

enum Status = active | draining | failed(string)
package infrastructure.v1
field 1
checked on decode
written explicitly
optional
a oneof

Enums with only unit variants become proto enums with an …_UNSPECIFIED zero; enums with payloads become a message with a oneof. Protobuf mapping, spec §11.2

What changes

TopicProtobufNOVASpec
Source of truth.proto filesA NOVA schema; the .proto is generated§11.2
Field numbers= 3 in the message@id(3), unique per record§6.1
Reading the dataNeeds the schemaText and NOVA binary are self-describing; Protobuf output is optional§3
ConstraintsTypes only; validation through plugins@range, @len and @key, checked after decoding§6.1
EvolutionRules by convention, such as never reusing a numberEach change classified; the SemVer bump is checked§6.5
TypesWell-known types for time; no decimalsTimestamps and durations map to the well-known types; decimals and rationals to strings§11.2

Migrating

Write the schema in NOVA, give every field an @id, and generate the .proto for the services that need it. The same schema encodes and decodes the wire format.

nvf schema proto infrastructure.novs > infrastructure.proto
nvf convert service.nova --to protobuf --schema infrastructure.novs -o service.pb
nvf convert service.pb --schema infrastructure.novs --to nova
Before you release a new version
nvf schema check infrastructure-1.0.0.novs infrastructure-1.1.0.novs

Features Protobuf cannot express, such as tuples, any or lists of lists, are rejected with an error naming the definition and field. Protobuf mapping, spec §11.2

When to stay with Protobuf

  • You define gRPC services and generate clients in many languages. NOVA generates messages, not services, and has Rust bindings only so far.
  • Your .proto files are the source of truth today. There is no importer from .proto to a NOVA schema.
  • You need a format that is stable today. NOVA is a 0.1 draft.

Questions

Is NOVA binary the same as the Protobuf wire format?

No. NOVA binary is self-describing and needs no schema. Protobuf output is a separate adapter that needs a schema with @id on every field.

What happens to fields that are absent on the wire?

An optional field stays absent, a nullable field becomes null, a field with a default gets it, and anything else gets the proto3 zero value. The decoded value is then validated against the schema.

Can I skip Protobuf and still get compact positional data?

For text, yes: the positional profile writes field values in schema order without names, for peers that hold the exact same schema.