opensearch-protobufs

opensearch-protobufs is the OpenSearch Project’s canonical source of .proto message and service definitions for OpenSearch’s gRPC-based client-server API, plus the generated client code built from them. Instead of hand-writing gRPC stubs against OpenSearch’s search, document, and ML services, this package ships pre-generated Python message classes and service clients (with equivalent Go, Java, and TypeScript artifacts released alongside it) derived directly from the OpenSearch API specification.

What You Get

• Generated Python message classes for OpenSearch requests/responses (SearchRequest, BulkRequest, IndexDocumentRequest, and more)
• gRPC service stubs (e.g. SearchServiceStub) for calling OpenSearch’s search, document, and ML services
• Raw .proto schema files (also distributed as a release ZIP) for regenerating clients in any protobuf-supported language
• Parallel Go, Java, and TypeScript generated packages built from the same source schemas
• Versioned releases tracking OpenSearch’s API surface via the upstream opensearch-api-specification

Common Use Cases

• Building high-performance clients that talk to OpenSearch over gRPC instead of REST/JSON
• Generating typed request/response objects for search, bulk indexing, and document operations against OpenSearch
• Integrating OpenSearch calls into polyglot systems that already standardize on protobuf/gRPC
• Regenerating custom-language clients from the canonical .proto schemas when an official generated package isn’t available

Under The Hood

Architecture: protos/schemas/ holds the shared protobuf message definitions (led by a large common.proto) and protos/services/ defines gRPC service contracts (search_service.proto, document_service.proto, ml_service.proto); a Bazel-based build (BUILD.bazel, WORKSPACE) plus Gradle tooling compiles these into per-language generated code that is packaged and released for Python, Go, Java, and TypeScript consumers. Tech Stack: Protocol Buffers/gRPC as the core technology, with Bazel and Gradle driving codegen and packaging, and CI (.github/workflows, Jenkins configs) validating schema changes against the upstream opensearch-api-specification. Code Quality: schema correctness is enforced through the specification-driven generation pipeline itself rather than hand-written unit tests of generated code; COMPATIBILITY.md and CHANGELOG.md document API-surface evolution and version compatibility guarantees release over release. API Design: because the schemas are generated directly from OpenSearch’s official API spec, the generated client method and field names track the REST API closely, minimizing the learning curve for developers already familiar with OpenSearch’s JSON API while gaining gRPC’s binary efficiency and strong typing.