Initial draft

Author: Andreas Sandberg

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to Agentic Product Protocol (APP)
+
+Thank you for your interest in contributing! We welcome improvements, bug fixes, and new ideas. Please read these guidelines to help maintain a high-quality, consistent, and collaborative project.
+
+---
+
+## Branching Model
+
+- **main**: The stable, released branch. All production-ready code lives here.
+- **feature branches**: For new features, bug fixes, or documentation updates, create a branch from `main`:
+  - Name your branch descriptively, e.g., `feature/add-filtering-support` or `fix/typo-in-rfc`.
+- **Pull Requests (PRs)**: All changes must be submitted via PR. Never commit directly to `main`.
+
+## Pull Request Guidelines
+
+- **Scope**: Keep PRs focused and minimal. Separate unrelated changes.
+- **Description**: Clearly describe the problem, solution, and any context.
+- **Tests**: If applicable, include or update tests/examples.
+- **Review**: At least one maintainer must review and approve before merging.
+- **Status Checks**: Ensure all CI checks pass before requesting review.
+- **Linked Issues**: Reference any related issues or RFCs in the PR description.
+
+## Spec Versioning & Review Process
+
+- **Versioning**: All breaking changes or new features to the protocol/specs must increment the version (e.g., `2025-10-06` → `2025-10-15`).
+- **Compatibility**: Maintain backward compatibility where possible. Document any breaking changes clearly in the changelog.
+- **Review**: Major changes (especially to RFCs, OpenAPI, or JSON Schemas) require:
+  - Discussion in a PR or issue
+  - Approval from at least one lead maintainer (see `MAINTAINERS.md`)
+
+## Required Updates for All Changes
+
+Every PR **must** include, as appropriate:
+
+- **OpenAPI / JSON Schema**: Update or add to `spec/openapi/` and `spec/json-schema/` as needed.
+- **Examples**: Add or update sample requests/responses in `examples/`.
+- **Changelog**: Add an entry to `changelog/unreleased.md` describing your change.
+- **Documentation**: Update `README.md` or relevant RFCs if behavior or usage changes.
+
+## Code of Conduct
+
+- Be respectful and constructive in all communications.
+- Assume good intent and work collaboratively.
+- Report unacceptable behavior to the maintainers listed in `MAINTAINERS.md`.
+
+## Getting Help
+
+- For questions, open a GitHub Discussion or Issue.
+- For urgent matters, contact a lead maintainer (see `MAINTAINERS.md`).
+
+---
+
+Thank you for helping make APP better!

LICENSE

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -187,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 Klarna Bank AB
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

MAINTAINERS.md

@@ -0,0 +1,17 @@
+# Maintainers
+
+Below are the current maintainers of the Agentic Product Protocol.
+
+## Lead maintainers
+
+- Community-driven (open for initial maintainers)
+
+## How to Become a Maintainer
+
+We welcome new maintainers who demonstrate:
+
+- Consistent contributions to the specification
+- Understanding of e-commerce and product data APIs
+- Commitment to the open standard and community governance
+
+Please open an issue expressing interest in becoming a maintainer.

README.md

@@ -1,67 +1,124 @@
-# Project Name
-> Short blurb about what your project does.
+# Agentic Product Protocol (APP)
+
+The **Agentic Product Protocol (APP)** is an interaction model and open standard for connecting AI agents and product data providers to enable seamless product discovery and comparison.
+
+The specification is maintained by the community and is currently in `draft`.
+
+- **For retailers & marketplaces** - Make your product catalog discoverable and searchable by AI agents while maintaining control of your inventory and pricing data.
+- **For AI agents** - Enable product discovery and comparison in your application, providing users with comprehensive product information and merchant offers.
+- **For comparison platforms** - Expose your aggregated product data through a standardized interface that AI agents can consume.
+
+Learn more at the [Agentic Product Protocol documentation](#).
+
+---
+
+## 📦 Repo Structure
+
+```plaintext
+<repo-root>/
+├── rfcs/
+│   └── rfc.*.md
+│
+├── spec/
+│   ├── openapi/
+│   │   └── openapi.*.yaml
+│   │
+│   └── json-schema/
+│       └── schema.*.json
+│
+├── examples/
+│   └── examples.*.json
+│
+├── changelog/
+│   └──  *.md
+│
+├── MAINTAINERS.md
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
 
-[![Build Status][ci-image]][ci-url]
-[![License][license-image]][license-url]
-[![Developed at Klarna][klarna-image]][klarna-url]
+---
 
+## 🔗 Quick Links
 
-One to two paragraph statement about your project and what it does.
+| Spec Type          | Latest Version                         | Description                                                        |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------ |
+| **RFC (Markdown)** | [rfcs/](rfcs/)                         | Human-readable design doc with rationale, flows, and rollout plan. |
+| **OpenAPI (YAML)** | [spec/openapi/](spec/openapi/)         | Machine-readable HTTP API spec for integrating product endpoints.  |
+| **JSON Schema**    | [spec/json-schema/](spec/json-schema/) | Data models for products, offers, and search results.              |
+| **Examples**       | [examples/](examples/)                 | Sample requests, responses.                                        |
+| **Changelog**      | [changelog/](changelog/)               | API version history and breaking changes.                          |
 
-## First steps
+---
 
-<details>
- <summary>Installation (for Admins)</summary>
-  
-  Currently, new repositories can be created only by a Klarna Open Source community lead. Please reach out to us if you need assistance.
-  
-  1. Create a new repository by clicking ‘Use this template’ button.
-  
-  2. Make sure your newly created repository is private.
-  
-  3. Enable Dependabot alerts in your candidate repo settings under Security & analysis. You need to enable ‘Allow GitHub to perform read-only analysis of this repository’ first.
-</details>
+## 🛠 Getting Started
 
-1. Update `README.md` and `CHANGELOG.md`.
+The Agentic Product Protocol provides standardized endpoints for:
 
-2. Optionally, clone [the default contributing guide](https://github.com/klarna-incubator/.github/blob/main/CONTRIBUTING.md) into `.github/CONTRIBUTING.md`.
+1. **Product Search** - Search and filter products with rich query capabilities
+2. **Product Listing** - Retrieve detailed product information with merchant offers
+3. **Category Discovery** - Browse product hierarchies and categories
 
-3. Do *not* edit `LICENSE`.
+To start building with APP:
 
-## Usage example
+1. Review this repo's [OpenAPI specs](spec/openapi/) and [JSON Schemas](spec/json-schema/).
+2. Implement the required endpoints on your product data platform.
+3. Test using the [examples](examples/) provided in this repo.
+4. Register your implementation with AI agent platforms.
 
-A few motivating and useful examples of how your project can be used. Spice this up with code blocks and potentially more screenshots.
+---
 
-_For more examples and usage, please refer to the [Docs](TODO)._
+## 📚 Documentation
 
-## Development setup
+| Area                 | Resource                                                                               |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| Product Search Spec  | [spec/openapi/openapi.product_search.yaml](spec/openapi/openapi.product_search.yaml)   |
+| Product Listing Spec | [spec/openapi/openapi.product_listing.yaml](spec/openapi/openapi.product_listing.yaml) |
 
-Describe how to install all development dependencies and how to run an automated test-suite of some kind. Potentially do this for multiple platforms.
+---
 
-```sh
-make install
-npm test
-```
+## 📝 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Branching model
+- Pull request guidelines
+- Spec versioning and review process
+
+All changes must include:
+
+- Updated OpenAPI / JSON Schemas
+- New or updated examples
+- Changelog entry in `changelog/unreleased.md`
+
+---
+
+## 🎯 Use Cases
+
+### Product Discovery
+
+AI agents can search across your entire product catalog using natural language queries, with support for filtering by price, category, brand, availability, and more.
+
+### Price Comparison
 
-## How to contribute
+Provide comprehensive merchant offers with pricing, shipping costs, stock status, and delivery times, enabling AI agents to help users find the best deals.
 
-See our guide on [contributing](.github/CONTRIBUTING.md).
+### Product Information
 
-## Release History
+Expose detailed product attributes including descriptions, images, ratings, reviews, and technical specifications in a standardized format.
 
-See our [changelog](CHANGELOG.md).
+---
 
-## License
+## 🔒 Security & Privacy
 
-Copyright © 2022 Klarna Bank AB
+- **Authentication** - All endpoints require Bearer token authentication
+- **Rate Limiting** - Implement appropriate rate limits to prevent abuse
+- **Data Privacy** - Follow applicable data protection regulations (GDPR, CCPA, etc.)
+- **PII Handling** - Minimize collection of personally identifiable information
 
-For license details, see the [LICENSE](LICENSE) file in the root of this project.
+---
 
+## 📜 License
 
-<!-- Markdown link & img dfn's -->
-[ci-image]: https://img.shields.io/badge/build-passing-brightgreen?style=flat-square
-[ci-url]: https://github.com/klarna-incubator/TODO
-[license-image]: https://img.shields.io/badge/license-Apache%202-blue?style=flat-square
-[license-url]: http://www.apache.org/licenses/LICENSE-2.0
-[klarna-image]: https://img.shields.io/badge/%20-Developed%20at%20Klarna-black?style=flat-square&labelColor=ffb3c7&logo=klarna&logoColor=black
-[klarna-url]: https://klarna.github.io
+Licensed under the [Apache 2.0 License](LICENSE).

changelog/2025-10-06.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 2025-10-06
+
+- Initial release of the Agentic Product Protocol specification.
+- Published the first version of:
+  - Product Search API specification and OpenAPI schema
+  - Product Listing API specification and OpenAPI schema
+- Added example JSON files for both product search and product listing flows.
+- Documentation and RFCs for both APIs included.
+- Defined standardized data models for products, offers, merchants, and pricing.
+- Established authentication and versioning requirements.

changelog/unreleased.md

@@ -0,0 +1,29 @@
+# Unreleased Changes
+
+This file tracks changes that have been made but not yet released.
+
+## Pending Features
+
+- JSON Schema validation files
+- Additional filtering options for advanced search
+- Category discovery API
+- Product review endpoints
+
+## Pending Improvements
+
+- Performance optimization guidelines
+- Caching strategy recommendations
+- Batch operation limits refinement
+
+## Breaking Changes
+
+None at this time.
+
+---
+
+When adding new entries:
+
+1. Categorize under appropriate heading (Features, Improvements, Fixes, Breaking Changes)
+2. Use bullet points with clear descriptions
+3. Reference PR numbers when applicable
+4. Move to dated changelog file upon release