Skip to content

Feedback Files

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.

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

[
  {
    "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

[
  {
    "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