156 lines
3.0 KiB
Markdown
156 lines
3.0 KiB
Markdown
|
|
|
|
# Instructions: Converting OpenRPC → Markdown Shorthand
|
|
|
|
## Purpose
|
|
|
|
Transform an OpenRPC specification (JSON or YAML) into a **dense Markdown format** that is:
|
|
|
|
* Human-readable
|
|
* AI-parseable
|
|
* Compact (minimal boilerplate)
|
|
* Faithful to the original semantics
|
|
|
|
---
|
|
|
|
## General Rules
|
|
|
|
1. **Drop metadata**
|
|
Ignore `info`, `servers`, and other metadata not relevant to API usage.
|
|
|
|
2. **Two main sections**
|
|
|
|
* `# Methods`
|
|
* `# Schemas`
|
|
|
|
3. **Method representation**
|
|
Each method gets its own `## {method_name}` block:
|
|
|
|
* First line: *description* (if present).
|
|
* **Params** section:
|
|
|
|
* List each parameter as `- name: TYPE (required?)`
|
|
* Inline object properties using nested bullet lists or YAML block if complex.
|
|
* **Result** section:
|
|
|
|
* Same style as params.
|
|
* Use shorthand for references:
|
|
|
|
* `$ref: "#/components/schemas/Comment"` → `Comment`
|
|
* Array of refs → `[Comment]`
|
|
|
|
4. **Schema representation**
|
|
Each schema gets its own `## {SchemaName}` block:
|
|
|
|
* Use fenced YAML block for properties:
|
|
|
|
```yaml
|
|
field: TYPE # description
|
|
```
|
|
* List required fields below the block:
|
|
`*Required: field1, field2*`
|
|
|
|
---
|
|
|
|
## Type Conventions
|
|
|
|
* `type: integer` → `int`
|
|
* `type: string` → `str`
|
|
* `type: boolean` → `bool`
|
|
* `type: object` → `object`
|
|
* `type: array` → `[TYPE]` (if items defined)
|
|
* `oneOf: [SchemaA, SchemaB]` → `SchemaA | SchemaB`
|
|
|
|
---
|
|
|
|
## Handling Complex Types
|
|
|
|
1. **Objects inside parameters or results**
|
|
|
|
* If small (≤3 fields), inline as `{ field1: TYPE, field2: TYPE }`.
|
|
* If large, expand as YAML block.
|
|
|
|
Example:
|
|
|
|
```markdown
|
|
- args (object, required)
|
|
- id: int
|
|
- parent: int
|
|
```
|
|
|
|
2. **Nested schemas (structs in structs)**
|
|
|
|
* Inline only the top level, reference nested schemas by name.
|
|
* If the nested schema is not declared in `components/schemas`, define it under `# Schemas`.
|
|
|
|
Example:
|
|
|
|
```markdown
|
|
## user_create
|
|
**Params**
|
|
- user: UserProfile (struct defined below)
|
|
```
|
|
|
|
3. **Arrays**
|
|
|
|
* `[TYPE]` for primitives (e.g., `[int]`).
|
|
* `[SchemaName]` for objects.
|
|
|
|
4. **Results with multiple options**
|
|
|
|
* Use `SchemaA | [SchemaA]` for "oneOf".
|
|
|
|
---
|
|
|
|
## Example Conversion
|
|
|
|
OpenRPC (fragment):
|
|
|
|
```json
|
|
{
|
|
"name": "comment_get",
|
|
"description": "Retrieve comments",
|
|
"params": [
|
|
{
|
|
"name": "args",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": { "type": "integer" },
|
|
"author": { "type": "integer" }
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"result": {
|
|
"name": "comments",
|
|
"schema": {
|
|
"oneOf": [
|
|
{ "$ref": "#/components/schemas/Comment" },
|
|
{ "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Markdown:
|
|
|
|
```markdown
|
|
## comment_get
|
|
Retrieve comments
|
|
|
|
**Params**
|
|
- args (object, required)
|
|
- id: int
|
|
- author: int
|
|
|
|
**Result**
|
|
- comments: Comment | [Comment]
|
|
```
|
|
|
|
---
|
|
|
|
This way, any AI (or human) can deterministically map **OpenRPC → Markdown shorthand**.
|