{"id":11598,"library":"protocol-buffers-schema","title":"Protocol Buffers Schema Parser","description":"protocol-buffers-schema is a minimalist JavaScript library designed for parsing Protocol Buffers (.proto) schema files into a structured JavaScript object and stringifying such objects back into the .proto format. It explicitly focuses on schema definition parsing rather than binary serialization or deserialization of actual Protobuf messages. The current stable version is 3.6.1, though the last npm publication (for 3.6.0) was approximately four years ago, suggesting a maintenance mode with an infrequent release cadence, if any. Its primary differentiator is its straightforward API for schema manipulation, contrasting with more comprehensive Protobuf libraries that include code generation, runtime encoding/decoding, and gRPC support. This package serves as a foundational component for tools that need to inspect or modify Protobuf definitions programmatically.","status":"maintenance","version":"3.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/mafintosh/protocol-buffers-schema","tags":["javascript","protobuf","protocol","buffers","schema","parser","parse"],"install":[{"cmd":"npm install protocol-buffers-schema","lang":"bash","label":"npm"},{"cmd":"yarn add protocol-buffers-schema","lang":"bash","label":"yarn"},{"cmd":"pnpm add protocol-buffers-schema","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is a CommonJS module. In ESM, `import schema from 'protocol-buffers-schema'` or `import * as schema from 'protocol-buffers-schema'` is the correct way to import the module's default export, which is the object containing `parse` and `stringify`.","wrong":"const { parse } = require('protocol-buffers-schema')","symbol":"schema","correct":"import schema from 'protocol-buffers-schema'"},{"note":"The `parse` function is a property of the default exported module object, not a named export. Attempting to destructure it directly as a named export will result in `undefined`.","wrong":"import { parse } from 'protocol-buffers-schema'","symbol":"parse","correct":"import schema from 'protocol-buffers-schema'; schema.parse(protoString);"},{"note":"While functional, chaining directly off `require()` is less readable and can complicate mocking in tests. Assigning to a variable first is preferred for clarity and consistency.","wrong":"require('protocol-buffers-schema').stringify(schemaObject)","symbol":"stringify","correct":"const schema = require('protocol-buffers-schema'); schema.stringify(schemaObject);"}],"quickstart":{"code":"import { readFileSync } from 'fs';\nimport schema from 'protocol-buffers-schema';\n\n// Create a dummy .proto file for demonstration\nconst protoContent = `\nsyntax = \"proto2\";\n\nmessage Point {\n  required int32 x = 1;\n  required int32 y = 2;\n  optional string label = 3;\n}\n\nmessage Line {\n  required Point start = 1;\n  required Point end = 2;\n  optional string label = 3;\n}\n`;\n\n// In a real scenario, this would be fs.writeFileSync('example.proto', protoContent);\n// For this quickstart, we'll parse the string directly.\n\n// Parse the .proto schema\nconst parsedSchema = schema.parse(protoContent);\n\n// Log the parsed JavaScript object representation of the schema\nconsole.log('Parsed Protobuf Schema:');\nconsole.log(JSON.stringify(parsedSchema, null, 2));\n\n// You can also stringify it back to .proto format\nconst stringifiedSchema = schema.stringify(parsedSchema);\nconsole.log('\\nStringified Protobuf Schema (reconstructed):');\nconsole.log(stringifiedSchema);\n\n// Example of accessing elements\nconsole.log('\\nFirst message name:', parsedSchema.messages[0].name);\nconsole.log('First field of first message:', parsedSchema.messages[0].fields[0].name);","lang":"javascript","description":"Demonstrates parsing a Protobuf schema string into a JavaScript object and then stringifying it back, also showing how to access parsed schema elements."},"warnings":[{"fix":"Use a dedicated Protobuf runtime library (e.g., `npm install protobufjs`) for encoding and decoding binary data.","message":"This package is a schema parser only. It does NOT provide functionality for encoding or decoding actual Protocol Buffers binary messages. For binary serialization/deserialization, consider libraries like `protobuf.js`, `google-protobuf`, or `protobuf-es`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the parsed output carefully for newer syntax. If issues arise, consider alternative, more actively maintained Protobuf parsing solutions or pre-process your .proto files to simpler forms if possible.","message":"The package (v3.6.1, last published ~4 years ago for 3.6.0) might not fully support all modern Protocol Buffers language features introduced in newer `proto3` specifications or `Protobuf Editions`. Ensure compatibility if working with very recent .proto syntax.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always use the latest stable version (3.6.1) to benefit from bug fixes and improved parsing logic. Consult the GitHub repository's commit history for specific changes between major versions if migrating from a very old version.","message":"Older versions of `protocol-buffers-schema` may have handled certain Protobuf syntax nuances differently. While no specific major breaking changes for schema parsing are widely documented for this library, the broader Protobuf ecosystem has had breaking changes, especially concerning generated code and runtime compatibility.","severity":"breaking","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This library only parses and stringifies Protobuf schema definitions. To encode or decode binary Protobuf messages, use a different library such as `protobuf.js` or `google-protobuf`.","cause":"Attempting to use `protocol-buffers-schema` for binary encoding/decoding, which it does not support.","error":"TypeError: schema.encode is not a function"},{"fix":"For CommonJS, use `const schema = require('protocol-buffers-schema'); schema.parse(...)`. For ESM, use `import schema from 'protocol-buffers-schema'; schema.parse(...)`.","cause":"Incorrectly importing the `parse` function as a named export instead of accessing it from the default module object.","error":"TypeError: Cannot read properties of undefined (reading 'parse')"},{"fix":"Ensure `syntax = \"proto2\";` is present in your `.proto` file if you intend to use explicit `required`/`optional` field rules. If using `proto3` without Editions, these keywords are not valid for field rules.","cause":"Parsing a `proto3` file that uses `required` or `optional` keywords for field rules without explicitly setting `syntax = \"proto2\"`. While `protocol-buffers-schema` supports both, `proto3` has different default field behaviors and `required`/`optional` are not standard field rules (except with Editions).","error":"SyntaxError: Unexpected token 'required' / 'optional'"}],"ecosystem":"npm"}