NOJIRA: Define ORSP 1.1 discovery profile

OEP-0001-discovery.md

@@ -0,0 +1,55 @@
+# OEP-0001: Standard discovery and browsing
+
+Status: **Candidate**  
+Target: **ORSP 1.1**
+
+## Problem
+
+ORSP 1.0 lets a reader search only after the user already knows a title or
+author. Independently implemented readers cannot offer interoperable featured
+shelves, category navigation, or latest-update feeds without source-specific
+extensions.
+
+## Proposal
+
+Reserve three optional standard capabilities and endpoint relations:
+
+| Capability | Endpoint | Response |
+| --- | --- | --- |
+| `discover` | `GET v1/discover` | Curated sections containing book objects |
+| `categories` | `GET v1/categories` | Stable category IDs and display names |
+| `browse` | `GET v1/browse` | Search-style pagination by category or sort |
+
+The standardized browse sorts are `latest` and `popular`. Sources may implement
+any optional capability independently except that `categories` requires
+`browse`, because category IDs are defined as browse inputs.
+
+## Compatibility
+
+- The four ORSP 1.0 core endpoints and object meanings are unchanged.
+- Existing 1.0 sources remain conforming core sources and require no changes.
+- Existing 1.x clients already ignore unknown capability tokens.
+- A client exposes discovery UI only after the corresponding capability is
+  advertised; otherwise it falls back to core search.
+- All new response objects use existing book metadata and forward-compatible
+  unknown-member handling.
+
+## Security and privacy
+
+The new endpoints are unauthenticated, safe, idempotent `GET` operations under
+the same response-size, redirect, caching, SSRF, and untrusted-input rules as
+the core profile. ORSP 1.1 does not define personal profiles or personalized
+recommendations. Sources must not imply that a curated section is personalized
+unless that behavior is documented outside the protocol.
+
+## Implementation evidence
+
+- The Open Reading Flutter client implements capability-gated discovery with
+  fallback to core search.
+- This repository's Dart reference source implements all three capabilities.
+- The conformance suite covers positive discovery/category/browse flows and
+  invalid browse sort behavior.
+
+Independent source and reader implementations are still required before the
+candidate can be declared a stable release under the governance acceptance
+gates.

README.es.md

@@ -30,6 +30,15 @@ GET {apiBaseUrl}v1/books/{bookId}/chapters?page=1&pageSize=100
 GET {apiBaseUrl}v1/books/{bookId}/chapters/{chapterId}
 ```
 
+La versión 1.1 también define operaciones opcionales de descubrimiento,
+categorías y exploración:
+
+```text
+GET {apiBaseUrl}v1/discover
+GET {apiBaseUrl}v1/categories
+GET {apiBaseUrl}v1/browse?category={categoryId}&sort=latest&page=1&pageSize=20
+```
+
 Consulta la [especificación](SPECIFICATION.md) y la definición
 [OpenAPI 3.1](openapi.yaml) para conocer todos los campos y errores.
 
@@ -57,7 +66,7 @@ emulador de Android.
 
 ## Estado y uso responsable
 
-La versión `1.0` es un borrador de estabilización. El flujo básico de lectura ya
+La versión `1.1` es un borrador candidato. El flujo básico de lectura ya
 ha sido verificado, pero se aceptan propuestas sobre autenticación,
 sincronización, paginación y formatos de contenido antes de declarar una
 versión estable.

README.ja.md

@@ -29,6 +29,14 @@ GET {apiBaseUrl}v1/books/{bookId}/chapters?page=1&pageSize=100
 GET {apiBaseUrl}v1/books/{bookId}/chapters/{chapterId}
 ```
 
+バージョン 1.1 では、任意のディスカバリー、カテゴリ、ブラウズ API も定義します。
+
+```text
+GET {apiBaseUrl}v1/discover
+GET {apiBaseUrl}v1/categories
+GET {apiBaseUrl}v1/browse?category={categoryId}&sort=latest&page=1&pageSize=20
+```
+
 フィールドとエラー処理の詳細は、[仕様書](SPECIFICATION.md)および
 [OpenAPI 3.1 定義](openapi.yaml)を参照してください。
 
@@ -55,7 +63,7 @@ PC では `http://127.0.0.1:8787`、Android エミュレーターでは
 
 ## ステータスと責任ある利用
 
-バージョン `1.0` は安定化ドラフトです。基本的な読書フローは検証済みですが、安定版の
+バージョン `1.1` は候補ドラフトです。基本的な読書フローは検証済みですが、安定版の
 公開前に、認証、同期、ページング、コンテンツ形式についてのフィードバックを歓迎します。
 
 ORSP は、オリジナル、パブリックドメイン、または正規に許諾されたコンテンツを対象とします。

README.ko.md

@@ -28,6 +28,14 @@ GET {apiBaseUrl}v1/books/{bookId}/chapters?page=1&pageSize=100
 GET {apiBaseUrl}v1/books/{bookId}/chapters/{chapterId}
 ```
 
+버전 1.1은 선택적 탐색, 카테고리 및 둘러보기 엔드포인트도 정의합니다.
+
+```text
+GET {apiBaseUrl}v1/discover
+GET {apiBaseUrl}v1/categories
+GET {apiBaseUrl}v1/browse?category={categoryId}&sort=latest&page=1&pageSize=20
+```
+
 필드와 오류 처리에 대한 자세한 내용은 [프로토콜 명세](SPECIFICATION.md)와
 [OpenAPI 3.1 문서](openapi.yaml)를 참고하세요.
 
@@ -54,7 +62,7 @@ PC에서는 `http://127.0.0.1:8787`, Android 에뮬레이터에서는
 
 ## 상태 및 책임 있는 사용
 
-프로토콜 `1.0`은 안정화 초안입니다. 핵심 읽기 흐름은 검증되었지만 안정 버전 발표 전까지
+프로토콜 `1.1`은 후보 초안입니다. 핵심 읽기 흐름은 검증되었지만 안정 버전 발표 전까지
 인증, 동기화, 페이지 처리 및 콘텐츠 형식에 대한 의견을 환영합니다.
 
 ORSP는 창작물, 퍼블릭 도메인 및 정식 허가를 받은 콘텐츠를 위한 것입니다. 접근 제어를

README.md

@@ -25,7 +25,7 @@ Every source publishes a discovery document:
 GET /.well-known/open-reading-source.json
 ```
 
-It then implements four standard API operations:
+It implements four core reading operations:
 
 ```text
 GET {apiBaseUrl}v1/search?q={query}&page=1&pageSize=20
@@ -34,21 +34,34 @@ GET {apiBaseUrl}v1/books/{bookId}/chapters?page=1&pageSize=100
 GET {apiBaseUrl}v1/books/{bookId}/chapters/{chapterId}
 ```
 
+ORSP 1.1 sources may additionally advertise a standard discovery profile:
+
+```text
+GET {apiBaseUrl}v1/discover
+GET {apiBaseUrl}v1/categories
+GET {apiBaseUrl}v1/browse?category={categoryId}&sort=latest&page=1&pageSize=20
+```
+
 These endpoint relations are resolved against the discovered `apiBaseUrl`.
-ORSP 1.0 Core Reading sources implement all four capabilities.
+ORSP 1.1 Core Reading sources implement all four core capabilities. Discovery,
+categories, and browsing are optional and capability-gated, so existing ORSP
+1.0 sources remain compatible.
 
 Example discovery document:
 
 ```json
 {
   "protocol": "open-reading-source",
-  "protocolVersion": "1.0",
+  "protocolVersion": "1.1",
   "id": "org.example.public-books",
   "name": "Example Public Books",
   "description": "Public-domain books maintained by Example.org",
   "apiBaseUrl": "https://books.example.org/api/",
   "languages": ["en"],
-  "capabilities": ["search", "detail", "catalog", "content"]
+  "capabilities": [
+    "search", "discover", "categories", "browse",
+    "detail", "catalog", "content"
+  ]
 }
 ```
 
@@ -68,6 +81,7 @@ ORSP-compatible reader. Android emulators should use `http://10.0.2.2:8787`.
 
 ```text
 SPECIFICATION.md              Normative protocol specification
+OEP-0001-discovery.md         ORSP 1.1 discovery proposal and compatibility analysis
 openapi.yaml                  OpenAPI 3.1 API description
 schemas/discovery.schema.json Discovery-document JSON Schema
 examples/dart_server.dart     Runnable reference source
@@ -79,7 +93,7 @@ registry/                     PR-based community source registry
 
 ## Status
 
-Protocol version `1.0` is a stabilization draft. Its compatibility rules,
+Protocol version `1.1` is a candidate draft. Its compatibility rules,
 machine-readable contracts, reference source, and core conformance tests are
 now developed together. Independent reader and source implementations are
 welcome before the specification is declared stable.

README.zh-CN.md

@@ -42,17 +42,20 @@ GET /.well-known/open-reading-source.json
 ```json
 {
   "protocol": "open-reading-source",
-  "protocolVersion": "1.0",
+  "protocolVersion": "1.1",
   "id": "org.example.public-books",
   "name": "示例公共图书源",
   "description": "由 Example.org 维护的公共领域图书",
   "apiBaseUrl": "https://books.example.org/api/",
   "languages": ["zh-CN"],
-  "capabilities": ["search", "detail", "catalog", "content"]
+  "capabilities": [
+    "search", "discover", "categories", "browse",
+    "detail", "catalog", "content"
+  ]
 }
 ```
 
-协议 1.0 定义四类核心接口：
+协议 1.1 保留四类核心接口：
 
 ```text
 GET {apiBaseUrl}v1/search?q={query}&page=1&pageSize=20
@@ -61,8 +64,17 @@ GET {apiBaseUrl}v1/books/{bookId}/chapters?page=1&pageSize=100
 GET {apiBaseUrl}v1/books/{bookId}/chapters/{chapterId}
 ```
 
-这些相对路径必须基于发现文档中的 `apiBaseUrl` 解析。ORSP 1.0 Core Reading 书源必须
-实现全部四项能力。完整字段与错误处理要求请阅读
+支持内容发现的书源还可以声明三个可选标准能力：
+
+```text
+GET {apiBaseUrl}v1/discover
+GET {apiBaseUrl}v1/categories
+GET {apiBaseUrl}v1/browse?category={categoryId}&sort=latest&page=1&pageSize=20
+```
+
+这些相对路径必须基于发现文档中的 `apiBaseUrl` 解析。ORSP 1.1 Core Reading 书源必须
+实现全部四项核心能力；发现、分类和浏览按能力声明启用，旧的 1.0 书源无需修改也可以
+继续搜索和阅读。完整字段与错误处理要求请阅读
 [协议规范](SPECIFICATION.md)，接口模型可查看 [OpenAPI 3.1 文档](openapi.yaml)。
 
 ## 快速运行测试书源
@@ -106,6 +118,7 @@ HTML 正文应被视为不可信输入，客户端在渲染前应进行清理。
 
 ```text
 SPECIFICATION.md                规范性协议说明
+OEP-0001-discovery.md           ORSP 1.1 发现能力提案与兼容性分析
 openapi.yaml                    OpenAPI 3.1 接口定义
 schemas/discovery.schema.json   发现文档 JSON Schema
 examples/dart_server.dart       可运行的 Dart 参考书源
@@ -118,7 +131,7 @@ registry/                       基于 PR 的社区书源目录
 
 ## 当前状态与兼容性
 
-协议版本 `1.0` 目前是稳定化草案。兼容性规则、机器可读契约、参考书源和核心一致性测试
+协议版本 `1.1` 目前是候选草案。兼容性规则、机器可读契约、参考书源和核心一致性测试
 会同步演进。在宣布稳定版本之前，欢迎独立阅读器和书源实现参与互操作验证。
 
 可以运行官方核心测试：

README.zh-TW.md

@@ -37,6 +37,14 @@ GET {apiBaseUrl}v1/books/{bookId}/chapters?page=1&pageSize=100
 GET {apiBaseUrl}v1/books/{bookId}/chapters/{chapterId}
 ```
 
+協議 1.1 亦提供可選的探索、分類與瀏覽端點：
+
+```text
+GET {apiBaseUrl}v1/discover
+GET {apiBaseUrl}v1/categories
+GET {apiBaseUrl}v1/browse?category={categoryId}&sort=latest&page=1&pageSize=20
+```
+
 完整欄位及錯誤處理請參閱[協議規範](SPECIFICATION.md)與
 [OpenAPI 3.1 文件](openapi.yaml)。
 
@@ -63,7 +71,7 @@ dart run examples/dart_server.dart
 
 ## 狀態與使用邊界
 
-協議 `1.0` 目前是穩定化草案。核心讀取流程已完成驗證，但在穩定版本發布前仍歡迎
+協議 `1.1` 目前是候選草案。核心讀取流程已完成驗證，但在穩定版本發布前仍歡迎
 對認證、同步、分頁及內容格式提出建議。
 
 ORSP 僅適用於原創、公共領域或合法授權內容。請勿用於繞過存取控制、違反服務條款或