0
# Apache Avro Toplevel
1

2
Apache Avro Toplevel is a meta-framework that coordinates the entire Apache Avro data serialization ecosystem across multiple programming languages. It provides shared schemas, build coordination, and cross-language compatibility standards for the comprehensive Avro data serialization system.
3

4
## Package Information
5

6
- **Package Name**: avro-toplevel
7
- **Package Type**: maven
8
- **Language**: Java (Framework Coordinator)
9
- **Installation**: `mvn dependency:get -Dartifact=org.apache.avro:avro-toplevel:1.12.0`
10

11
## Core Imports
12

13
This meta-framework doesn't provide direct programming APIs. Instead, it coordinates language-specific implementations:
14

15
```xml { .api }
16
<!-- Maven POM dependency for build coordination -->
17
<dependency>
18
    <groupId>org.apache.avro</groupId>
19
    <artifactId>avro-toplevel</artifactId>
20
    <version>1.12.0</version>
21
    <type>pom</type>
22
</dependency>
23
```
24

25
## Basic Usage
26

27
The Avro Toplevel project is primarily used for:
28

29
```bash
30
# Clone and build entire Avro ecosystem
31
git clone https://github.com/apache/avro.git
32
cd avro
33
./build.sh
34

35
# Access shared schemas and specifications
36
ls share/schemas/org/apache/avro/
37
```
38

39
## Architecture
40

41
Apache Avro Toplevel serves as the central orchestrator for a comprehensive data serialization ecosystem:
42

43
- **Framework Coordination**: Manages builds and dependencies across 10+ language implementations
44
- **Schema Registry**: Provides shared Avro schemas for RPC, serialization, and MapReduce integration
45
- **Cross-Language Standards**: Ensures compatibility and consistency across all language implementations
46
- **Development Infrastructure**: Includes build tools, testing frameworks, and documentation systems
47
- **Version Management**: Coordinates versioning and releases across the entire ecosystem
48

49
## Capabilities
50

51
### Framework Coordination
52

53
Central coordination and build management for the entire Apache Avro ecosystem, supporting multi-language implementations and cross-platform compatibility.
54

55
```xml { .api }
56
<!-- Maven coordinates for the framework coordinator -->
57
<groupId>org.apache.avro</groupId>
58
<artifactId>avro-toplevel</artifactId>
59
<version>1.12.0</version>
60
<packaging>pom</packaging>
61
```
62

63
[Framework Coordination](./framework-coordination.md)
64

65
### Shared Schema Registry
66

67
Core Avro schemas used across all language implementations for serialization, RPC communication, and data interchange protocols.
68

69
```json { .api }
70
// Example: IPC Handshake Request Schema Structure
71
{
72
  "type": "record",
73
  "name": "HandshakeRequest", 
74
  "namespace": "org.apache.avro.ipc",
75
  "fields": [
76
    {"name": "clientHash", "type": {"type": "fixed", "name": "MD5", "size": 16}},
77
    {"name": "clientProtocol", "type": ["null", "string"], "default": null},
78
    {"name": "serverHash", "type": "MD5"},
79
    {"name": "meta", "type": ["null", {"type": "map", "values": "bytes"}], "default": null}
80
  ]
81
}
82
```
83

84
[Schema Registry](./schema-registry.md)
85

86
### Language Implementation References
87

88
References and coordination for language-specific Avro implementations across C, C++, C#, Java, JavaScript, Perl, PHP, Python, Ruby, and Rust.
89

90
```yaml { .api }
91
# Supported Language Implementations
92
implementations:
93
  - language: java
94
    location: lang/java
95
    artifacts: [avro, avro-compiler, avro-ipc, avro-tools]
96
  - language: python
97
    location: lang/py
98
    package: avro-python3
99
  - language: javascript
100
    location: lang/js
101
    package: avro-js
102
  - language: csharp
103
    location: lang/csharp
104
    package: Apache.Avro
105
```
106

107
[Language Implementations](./language-implementations.md)
108

109
### Build and Development Tools
110

111
Comprehensive build system and development infrastructure for cross-platform development and testing of the Avro ecosystem.
112

113
```bash { .api }
114
# Build system interface
115
./build.sh                    # Build all language implementations
116
./build.sh test              # Run cross-language compatibility tests
117
./build.sh clean             # Clean all build artifacts
118
./build.sh doc               # Generate documentation for all languages
119
```
120

121
[Build Tools](./build-tools.md)
122

123
## Types
124

125
```yaml { .api }
126
# Project Structure Types
127
AvroToplevelProject:
128
  groupId: "org.apache.avro"
129
  artifactId: "avro-toplevel"
130
  version: string
131
  packaging: "pom"
132
  modules: LanguageImplementation[]
133

134
LanguageImplementation:
135
  language: string
136
  location: string
137
  buildSystem: string
138
  mainArtifacts: string[]
139

140
SchemaDefinition:
141
  name: string
142
  namespace: string
143
  type: "record" | "enum" | "array" | "map" | "union" | "fixed"
144
  location: string
145
  description: string
146

147
BuildConfiguration:
148
  script: string
149
  commands: string[]
150
  environment: map[string, string]
151
  dependencies: string[]
152
```