{"id":20131288,"url":"https://github.com/qzed/serde_tagged","last_synced_at":"2025-04-09T16:40:47.846Z","repository":{"id":57666765,"uuid":"123735779","full_name":"qzed/serde_tagged","owner":"qzed","description":"Tag values during serialization, retreive tags during deserialization.","archived":false,"fork":false,"pushed_at":"2025-03-16T05:36:16.000Z","size":162,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T18:52:13.424Z","etag":null,"topics":["rust","serde","trait-objects"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qzed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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}},"created_at":"2018-03-03T22:11:49.000Z","updated_at":"2025-03-16T03:01:59.000Z","dependencies_parsed_at":"2024-11-13T20:47:31.511Z","dependency_job_id":"38e29f7b-7c6b-4772-8da3-e05e79fd8831","html_url":"https://github.com/qzed/serde_tagged","commit_stats":{"total_commits":56,"total_committers":1,"mean_commits":56.0,"dds":0.0,"last_synced_commit":"9762b998d2d55bd5f3274ccc94e44a5806c36204"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qzed%2Fserde_tagged","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qzed%2Fserde_tagged/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qzed%2Fserde_tagged/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qzed%2Fserde_tagged/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qzed","download_url":"https://codeload.github.com/qzed/serde_tagged/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248068903,"owners_count":21042577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["rust","serde","trait-objects"],"created_at":"2024-11-13T20:47:25.762Z","updated_at":"2025-04-09T16:40:47.827Z","avatar_url":"https://github.com/qzed.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serde Tagged\n\n[![Build Status]][github_actions] [![Coverage]][codecov] [![crates.io]][crates-io] [![docs.rs]][docs-rs]\n\n[Build Status]: https://github.com/qzed/serde_tagged/workflows/CI/badge.svg\n[github_actions]: https://github.com/qzed/serde_tagged/actions/workflows/ci.yml\n[Coverage]: https://codecov.io/gh/qzed/serde_tagged/branch/master/graph/badge.svg\n[codecov]: https://codecov.io/gh/qzed/serde_tagged\n[crates.io]: https://img.shields.io/crates/v/serde_tagged.svg\n[crates-io]: https://crates.io/crates/serde_tagged\n[docs.rs]: https://docs.rs/serde_tagged/badge.svg\n[docs-rs]: https://docs.rs/serde_tagged\n\nTag values during serialization, retrieve tags during deserialization.\n\n[Serde][serde] is a powerful, efficient and generic serialization framework for the rust language.\nIt does, however, not (directly) support de-/serialization of trait-objects.\nEspecially deserialization of a trait-object whose type cannot be determined beforehand requires an additional layer of code to retrieve said type based on information that can be stored in the data format.\n\nThis library aims to provide a framework to store tags that can contain type information in combination with a value during serialization, and retrieve them during deserialization.\nTo this end, multiple tagging-formats are provided, which are independent\u003csup\u003e[1](#format-restrictions)\u003c/sup\u003e of the data format being used.\nThe tagging-formats are largely similar to the [enum tagging-formats already used in serde][serde-enums].\n\n\u003ca name=\"myfootnote1\"\u003e[1]\u003c/a\u003e:\nSome data formats may however impose restrictions, e.g. JSON objects can only contain strings as keys, which in turn restricts the tag type that can be used with the external tagging-format to strings for a JSON backend.\n\n## Tagging formats\n\n`serde_tagged` supports multiple tagging formats.\nHere is a short overview:\n\n### External tagging\n\nThe external tagging format applies tags using a map with a single entry, where a tag is the key and the value the value of the entry. In a somewhat illustrative form, this would yield\n\n```text\n{ \u003ctag\u003e =\u003e \u003cvalue\u003e }\n```\n\nwhere `value` can be any de-/serializable value, `tag` however may be limited by the format being used (e.g. JSON would only allow strings).\nA benefit of this format is that it is somewhat readable when serialized to a human-readable data format but can also be compact when serialized to a binary format.\nFurthermore, due to the clear order (tag before value), deserialization can be faster than with some of the other formats (such as internal and non-tuple-based adjacent tagging).\nHowever, for configuration files and primarily text based data formats you might want to look at the internal tagging format.\n\n### Internal tagging\n\nThis format tags values internally, meaning that the tag is embedded into the value.\nEmbedding a tag does however not work with all value types (e.g. primitives such as `i32`).\n\nA big benefit of this format is that it is (subjectively) more readable in configuration files.\nA TOML configuration file using this tagging scheme could look somewhat like this:\n\n```toml\n[log]\ntype = \"terminal\"   # this is the tag\nlevel = \"trace\"     # this is a value-specific entry\ncolor = \"auto\"      # this is another value-specific entry\n```\n\nParsing this format, however, requires allocations so you might want to choose another format when the data format you are using is binary and/or you care about performance.\n\n### Adjacent tagging using tuples\n\nThe tuple-based adjacent format is similar to the external format compact, easy to deserialize due to its predefined tag value order, however, arguably less readable.\nTag and value pairs are stored as tuples, i.e.\n\n```text\n( \u003ctag\u003e, \u003cvalue\u003e )\n```\n\n### Adjacent tagging using maps\n\nThe map-based adjacent tagging format applies tags using two map entries, where one entry contains a mapping from tag-key to tag and the other entry a mapping from value-key to value.\nIllustrated, this yields\n\n```text\n{ \u003ctag-key\u003e =\u003e \u003ctag\u003e, \u003cvalue-key\u003e =\u003e \u003cvalue\u003e }\n```\n\nThis format again makes more sense when used in a human-readable data format, however also requires potential heap allocations for deserialization due to the order of tag and value being undefined.\n\n### Adjacent tagging using structs\n\nThe struct-based adjacent tagging format is similar to the map-based adjacent tagging format, however, here the tagged value is serialized as struct where the keys are the names of the struct fields.\nIllustrated, this yields\n\n```text\n{ \u003ctag-key\u003e: \u003ctag\u003e, \u003cvalue-key\u003e: \u003cvalue\u003e }\n```\n\nThe representation of this tagging format in the data format largely depends on the latter, thus it can be either compact (msgpack, bincode) or verbose (JSON).\n\n## Usage\n\nHave a look at the [examples][examples] directory.\nA good starting point would be the [trait-object example][examples-trait_obj].\nThis example explains all the relevant details regarding de-/serialization of trait-objects using the external tagging format (other formats can be used quite similar).\nOf course you can not only serialize and deserialize trait-objects, but any serializable and deserializable value with a tag.\nAlso, have a look at the [API documentation][api-doc].\n\n[examples]: https://github.com/qzed/serde_tagged/tree/master/examples\n[examples-trait_obj]: https://github.com/qzed/serde_tagged/blob/master/examples/trait_objects.rs\n[api-doc]: https://docs.rs/serde_tagged\n\n## Optional features\n\nBy default, this crate is built with the `erased` feature enabled (which requires `erased-serde` as dependency).\nThis feature is intended to simplify the deserialization of type-erased trait objects by providing types and traits to simplify interactions with `erased-serde`.\n\n## License\n\nLicensed under either of\n\n* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n\n[serde]: https://github.com/serde-rs/serde\n[serde-enums]: https://serde.rs/enum-representations.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqzed%2Fserde_tagged","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqzed%2Fserde_tagged","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqzed%2Fserde_tagged/lists"}