initial draft commit

README.md

@@ -1,2 +1,68 @@
 # emission-api-lib
 
+`emission-api-lib` is the authoritative draft specification for provider-neutral emission calculation connectors.
+
+The project defines a shared domain model, provider configuration format, provider capability vocabulary and validation artifacts for integrating multiple emission calculation providers through a stable connector layer.
+
+## Status
+
+Draft specification.
+
+The specification is not stable yet. Breaking changes are expected until the first stable version is released.
+
+## Purpose
+
+Direct integrations between specialist applications and individual emission calculation APIs create long-term dependencies on provider-specific request formats, response formats and feature assumptions.
+
+`emission-api-lib` defines a provider-neutral integration boundary. Applications should be able to express an emission calculation request in a stable domain format, while provider-specific mappings, capabilities and limitations are handled by connector implementations.
+
+## Repository role
+
+This repository is authoritative.
+
+Language-specific repositories implement this specification, but do not define it.
+
+- `emission-api-lib-java` is the Java reference implementation.
+- `emission-api-lib-python` is the Python implementation.
+- `emission-api-lib-php` is the PHP implementation.
+
+All implementation repositories should link back to this repository.
+
+## Provider scope
+
+The specification is designed for multiple providers from the beginning.
+
+A provider is described through XML configuration and machine-readable capability metadata. Implementations may use this information to validate requests, select providers, explain unsupported features and normalize responses.
+
+## Specification artifacts
+
+This repository may contain:
+
+- `schema.json` for the shared domain model
+- XSD files for provider XML validation
+- provider XML examples
+- normalized request and response examples
+- provider capability definitions
+- compatibility notes for language-specific implementations
+
+## Initial domain
+
+The first target domain is flight emission calculation.
+
+The specification is expected to support provider capability discovery instead of assuming that every provider supports the same request structure, response structure or calculation options.
+
+## Design principles
+
+- Provider neutrality
+- Multiple providers from the beginning
+- Stable domain-level request and response concepts
+- Explicit provider capabilities
+- Configuration over hardcoded provider logic
+- Replayability and auditability where supported
+- Language implementations that follow the shared specification
+
+## License
+
+The general specification repository is licensed under the GNU Affero General Public License, Version 3 or later.
+
+Individual implementation repositories may use a different license if this improves integration and adoption. Each implementation repository must state its license clearly.