---
canonical: https://docs.jentic.com/reference/public-apis/feedback-files/
representation: markdown-alternate
# Canonical page: https://docs.jentic.com/reference/public-apis/feedback-files/
# This is the Markdown alternate of the page above.
description: >-
  Learn how feedback.json files in Jentic Public APIs document repairs to OpenAPI
  Descriptions — what changed, why, and when — as an audit trail against regress.
---

# Feedback Files

!!! warning "Deprecated"
    This page is **deprecated** and kept only for reference. `feedback.json` files are no longer part
    of the current workflow. For how the Jentic API Directory repository is organised today, see
    [OAK Repository Structure](./oak-structure.md).

`feedback.json` files document **repairs and improvements** made to OpenAPI Descriptions: what changed, why, and when.

They provide:
- **Documentation** — audit trail of fixes
- **Prevention** — avoid reintroducing past issues

---

## Schema

```json
[
  {
    "repaired_file": "openapi.json",
    "repairs": [
      {
        "issue": {
          "message": "string",
          "level": "error|warning|improvement",
          "location": { "jsonPath": "string" }
        },
        "action_taken": "string",
        "source": "human|LLM-suggestion|automated-tool",
        "timestamp": "ISO 8601 timestamp"
      }
    ]
  }
]
```

**Location**

```
__data__/apis/openapi/<vendor>/<api>/<version>/feedback.json
```

**Example**

```json
[
  {
    "repaired_file": "openapi.json",
    "repairs": [
      {
        "issue": {
          "message": "Security scheme description incomplete",
          "level": "warning",
          "location": { "jsonPath": "#/components/securitySchemes/basicAuth/description" }
        },
        "action_taken": "Clarified API key usage with basic auth",
        "source": "human",
        "timestamp": "2025-05-23T09:50:50.000000"
      }
    ]
  }
]
```

---

## Best practices

* Keep **messages** specific and actionable
* Use **accurate `jsonPath`** pointers
* Prefer **small, frequent** repair records