Embeds a compiled PB schema into a module at compile time.

This is the compile-time counterpart to the runtime flow of reading a descriptor set, calling PB.decode_descriptor_set/1, and then PB.compile/1. Runtime schema maps remain fully supported; use this module when a schema is stable enough to travel with the compiled BEAM code.

Descriptor file

defmodule MyApp.Schema do
  use PB.Schema, descriptor: "priv/proto/schema.binpb"
end

The descriptor file must be a binary google.protobuf.FileDescriptorSet, such as one produced by:

protoc --descriptor_set_out=priv/proto/schema.binpb --include_imports your.proto

Relative descriptor paths are resolved from the compiler working directory (the Mix project root during normal Mix compilation). The generated module is marked with @external_resource, so Mix recompiles it when the descriptor file changes.

Add :projections to attach message-level adapters and structural term representations to the embedded schema:

defmodule MyApp.Schema do
  use PB.Schema,
    descriptor: "priv/proto/schema.binpb",
    projections: [
      {:"google.protobuf.Timestamp", adapter: MyApp.Timestamp.adapter()},
      {:"my.app.User", struct: MyApp.User},
      {:"my.app.Wrapper", unwrap: :value, preserved_unknown_fields: :reject},
      {:"my.app.Event", oneofs: [data: [representation: :identity]]}
    ]
end

Structural projections can also be declared in proto source with the elixir.pb.v1 custom options. Use compile-time :projections only when attaching adapters or compiling overrides for third-party schemas or generated descriptor sets you do not own.

Descriptor set map

For hand-authored schemas or tests, pass the decoded descriptor set map directly:

defmodule MyApp.Schema do
  use PB.Schema,
    descriptor_set: %{
      file: [
        %{
          name: "greeter.proto",
          package: :greeter,
          syntax: :proto3,
          message_type: [
            %{
              name: :HelloRequest,
              field: [
                %{name: :name, number: 1, type: :TYPE_STRING, label: :LABEL_OPTIONAL}
              ]
            }
          ]
        }
      ]
    }
end

Generated API

A schema module exposes:

• __pb_schema__/0 — callback returning the embedded compiled schema.
• schema/0 — public convenience alias for the callback.
• encode/2,3 and encode!/2,3 — call PB.encode/4 and PB.encode!/4.
• encode_iodata/2,3 and encode_iodata!/2,3 — call PB.encode_iodata/4 and PB.encode_iodata!/4 for zero-copy iodata output.
• decode/2,3 and decode!/2,3 — call PB.decode/4 and PB.decode!/4.
• normalize/2,3 and normalize!/2,3 — call PB.normalize/4 and PB.normalize!/4.
• validate/2,3 and validate!/2,3 — call PB.Validate.validate/4 and PB.Validate.validate!/4.

The top-level PB, PB.Validate, and PB.JSON entry points accept the schema module directly in place of a compiled schema map.

Introspection

This module also exposes lookup helpers that return public PB.Schema.Info structs — use these instead of reading the compiled-schema map directly:

• list_messages/1, fetch_message/2, message!/2
• list_enums/1, fetch_enum/2, enum!/2
• list_services/1, fetch_service/2, service!/2
• list_extensions/1, fetch_extension/2, extension!/2

Every lookup accepts either a compiled schema map or a use PB.Schema module. The bang variants raise PB.SchemaError (with kind: :unknown_* and operation: :introspect) on miss; the fetch_* variants return {:ok, info} | :error. The returned Info structs are the public stable surface — the compiled-schema internals may change without notice.