{"id":47700658,"url":"https://github.com/z5labs/avro-go","last_synced_at":"2026-04-02T17:08:50.723Z","repository":{"id":345426148,"uuid":"1184922684","full_name":"z5labs/avro-go","owner":"z5labs","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-27T06:30:24.000Z","size":39,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T16:00:32.525Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/z5labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T04:03:29.000Z","updated_at":"2026-03-27T06:29:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/z5labs/avro-go","commit_stats":null,"previous_names":["z5labs/avro-go"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/z5labs/avro-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favro-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favro-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favro-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favro-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/z5labs","download_url":"https://codeload.github.com/z5labs/avro-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favro-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31311224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T17:08:50.027Z","updated_at":"2026-04-02T17:08:50.715Z","avatar_url":"https://github.com/z5labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# avro\n\nA library for working with [Apache Avro](https://avro.apache.org/) encoded data in Go.\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| `github.com/z5labs/avro-go` | Binary encoding and decoding of Avro primitives |\n| `github.com/z5labs/avro-go/canonical` | Parsing Canonical Form schema types with JSON marshaling |\n| `github.com/z5labs/avro-go/idl` | Avro IDL tokenizer, parser, and printer |\n\n---\n\n## `avro` — Binary Encoding\n\n### Marshaling\n\nImplement `BinaryMarshaler` on your type and call `MarshalBinary` to encode it:\n\n```go\ntype Message struct {\n    Content string\n}\n\nfunc (m Message) MarshalAvroBinary(w *avro.BinaryWriter) error {\n    return w.WriteString(m.Content)\n}\n\nvar buf bytes.Buffer\nerr := avro.MarshalBinary(\u0026buf, Message{Content: \"hello\"})\n```\n\n`BinaryWriter` exposes one write method per Avro primitive:\n\n| Method | Avro type |\n|--------|-----------|\n| `WriteBool(bool)` | boolean |\n| `WriteInt(int32)` | int |\n| `WriteLong(int64)` | long |\n| `WriteFloat(float32)` | float |\n| `WriteDouble(float64)` | double |\n| `WriteBytes([]byte)` | bytes |\n| `WriteFixed([]byte)` | fixed |\n| `WriteString(string)` | string |\n\n### Unmarshaling\n\nImplement `BinaryUnmarshaler` on your type and call `UnmarshalBinary` to decode it:\n\n```go\nfunc (m *Message) UnmarshalAvroBinary(r *avro.BinaryReader) error {\n    var err error\n    m.Content, err = r.ReadString()\n    return err\n}\n\nvar msg Message\nerr := avro.UnmarshalBinary(bytes.NewReader(data), \u0026msg)\n```\n\n`BinaryReader` mirrors `BinaryWriter` with corresponding `Read*` methods.\n\n### Single-Object Encoding\n\nThe [Avro single-object encoding](https://avro.apache.org/docs/current/specification/#single-object-encoding) prepends a 2-byte magic header and an 8-byte schema fingerprint to the binary payload, allowing readers to identify the schema at runtime.\n\nImplement `SingleObjectMarshaler` (embeds `BinaryMarshaler` plus a `Fingerprint() [8]byte` method) and call `MarshalSingleObject`:\n\n```go\nfunc (m Message) Fingerprint() [8]byte {\n    var fp [8]byte\n    binary.LittleEndian.PutUint64(fp[:], avro.Fingerprint64([]byte(`\"string\"`)))\n    return fp\n}\n\nvar buf bytes.Buffer\nerr := avro.MarshalSingleObject(\u0026buf, msg)\n```\n\nDecode with `SingleObjectUnmarshaler` and `UnmarshalSingleObject`:\n\n```go\nvar msg Message\nerr := avro.UnmarshalSingleObject(r, \u0026msg)\n```\n\n`UnmarshalSingleObject` returns `ErrBadMagic` when the header is invalid and `ErrFingerprintMismatch` when the schema fingerprint in the payload does not match the one returned by `Fingerprint()`.\n\n### Schema Fingerprinting\n\n`Fingerprint64` computes the 64-bit Rabin fingerprint (CRC-64-AVRO) of a schema JSON string, as defined in the Avro specification:\n\n```go\nfp := avro.Fingerprint64([]byte(`\"string\"`))\n```\n\n---\n\n## `canonical` — Parsing Canonical Form\n\nThe `canonical` package provides typed Go representations of Avro schemas in [Parsing Canonical Form](https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas). The top-level `Schema` type implements `json.Marshaler` and `json.Unmarshaler`, producing canonical JSON with correct field ordering and no extra whitespace.\n\n### Creating schemas\n\nUse the constructor functions to build schemas:\n\n```go\ns := canonical.RecordSchema(canonical.Record{\n    Name: \"com.example.Person\",\n    Fields: []canonical.Field{\n        {Name: \"name\", Type: canonical.PrimitiveSchema(canonical.String)},\n        {Name: \"age\", Type: canonical.PrimitiveSchema(canonical.Int)},\n    },\n})\n```\n\nPrimitive constants are provided for all Avro primitives: `Null`, `Boolean`, `Int`, `Long`, `Float`, `Double`, `Bytes`, `String`.\n\n### Marshaling to canonical JSON\n\n```go\nb, err := json.Marshal(s)\n// {\"name\":\"com.example.Person\",\"type\":\"record\",\"fields\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"age\",\"type\":\"int\"}]}\n```\n\n### Unmarshaling from canonical JSON\n\n```go\nvar s canonical.Schema\nerr := json.Unmarshal(data, \u0026s)\n\nr, ok := s.Record()\nif ok {\n    fmt.Println(r.Name) // com.example.Person\n}\n```\n\nAccessor methods (`Primitive()`, `Record()`, `Enum()`, `Array()`, `Map()`, `Union()`, `Fixed()`) provide type-safe access to the underlying concrete type.\n\n### Converting from IDL\n\n`SchemaFrom` converts a parsed `idl.Schema` into canonical form:\n\n```go\nf, err := idl.Parse(strings.NewReader(`\n    namespace com.example;\n    schema int;\n    record Person {\n        string name;\n        int    age;\n    }\n`))\n\nschemas, err := canonical.SchemaFrom(f.Schema)\n\nb, err := json.Marshal(schemas[1])\n// {\"name\":\"com.example.Person\",\"type\":\"record\",\"fields\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"age\",\"type\":\"int\"}]}\n```\n\nThe function returns a slice because an IDL schema can define multiple named types. Namespace qualification, type references, and all structural schema information are preserved; non-canonical attributes (doc comments, aliases, defaults) are stripped.\n\n---\n\n## `idl` — Avro IDL\n\nThe `idl` package parses [Avro IDL](https://avro.apache.org/docs/current/idl-language/) source files into an AST and can print an AST back to IDL text.\n\n### Parsing\n\n`Parse` reads an Avro IDL source from any `io.Reader` and returns a `*File` AST:\n\n```go\nf, err := idl.Parse(strings.NewReader(`\n    namespace com.example;\n    schema record User {\n        string name;\n        int    age;\n    }\n`))\n```\n\nThe `File` struct contains either a `*Schema` or a `*Protocol`. A `*Schema` holds the top-level named types (`Record`, `Enum`, `Fixed`) and primitive type identifiers.\n\n### Printing\n\n`Print` formats a `*File` AST back to Avro IDL text:\n\n```go\nvar buf bytes.Buffer\nerr := idl.Print(\u0026buf, f)\nfmt.Println(buf.String())\n```\n\n### Tokenizing\n\n`Tokenize` exposes the low-level lexer as an `iter.Seq2[Token, error]` iterator (Go 1.23+):\n\n```go\nfor tok, err := range idl.Tokenize(r) {\n    if err != nil {\n        // handle error\n    }\n    fmt.Println(tok)\n}\n```\n\nToken types include `TokenComment`, `TokenDocComment`, `TokenIdentifier`, `TokenSymbol`, `TokenString`, `TokenNumber`, and `TokenAnnotation`.\n\n---\n\n## License\n\nReleased under the [MIT License](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz5labs%2Favro-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fz5labs%2Favro-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz5labs%2Favro-go/lists"}