> ## Documentation Index > Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Validate knowledge files > Check knowledge files before using them as context in a form comparison. A knowledge file is a UTF-8 Markdown file in your files: YAML front matter (format: forms-knowledge/v1, namespace, title, optional scope), optional intro prose, then one entry per level-two heading. Each heading is followed immediately by a fenced yaml block and a Markdown body. Entry fields: id (a lowercase segment; the full ID is namespace:id), type (concept, definition or guidance), kind (concepts only: coverage, exposure, party_role, act, loss, claim, benefit, condition or term), definitionOf (definitions only: the full ID of a concept), scope (required on definitions), and optional label, aliases, connections ({ relation, target, note? } with a full target ID) and sources ({ fileId, page?, section?, quote? }, { fileId?, entryId } or { url }). The files are checked together: full IDs must be unique across them, and every connection and definitionOf target must be an entry in one of them. Connection cycles are allowed. Returns 200 with valid: false and diagnostics when content is invalid; valid is true when no diagnostic is an error, and only then are entries listed. Validation checks structure, not whether the prose or a cited passage is right. Reads the current version of each file and changes nothing; repeat it freely. Requires read and download access to each file and the form comparisons feature for your organization. Free. ## OpenAPI ````yaml /openapi.json post /insurance/form-knowledge/validate openapi: 3.0.3 info: title: Effective API version: 2.0.0 description: The public Effective REST API. Authenticate using an Effective API key. servers: - url: https://api.effectiveai.app/api/v2 description: Production security: - bearerAuth: [] paths: /insurance/form-knowledge/validate: post: tags: - Form comparisons summary: Validate knowledge files description: >- Check knowledge files before using them as context in a form comparison. A knowledge file is a UTF-8 Markdown file in your files: YAML front matter (format: forms-knowledge/v1, namespace, title, optional scope), optional intro prose, then one entry per level-two heading. Each heading is followed immediately by a fenced yaml block and a Markdown body. Entry fields: id (a lowercase segment; the full ID is namespace:id), type (concept, definition or guidance), kind (concepts only: coverage, exposure, party_role, act, loss, claim, benefit, condition or term), definitionOf (definitions only: the full ID of a concept), scope (required on definitions), and optional label, aliases, connections ({ relation, target, note? } with a full target ID) and sources ({ fileId, page?, section?, quote? }, { fileId?, entryId } or { url }). The files are checked together: full IDs must be unique across them, and every connection and definitionOf target must be an entry in one of them. Connection cycles are allowed. Returns 200 with valid: false and diagnostics when content is invalid; valid is true when no diagnostic is an error, and only then are entries listed. Validation checks structure, not whether the prose or a cited passage is right. Reads the current version of each file and changes nothing; repeat it freely. Requires read and download access to each file and the form comparisons feature for your organization. Free. operationId: validateFormKnowledge requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2ValidateFormKnowledgeRequest' responses: '200': description: Validation result for the whole set. content: application/json: schema: $ref: '#/components/schemas/V2FormKnowledgeValidation' '400': description: >- invalid_request: the body is malformed, lists 0 or more than 10 files or a file twice, or a file is not UTF-8 text or is larger than 1 MiB. details names the file by its position in files. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: >- feature_not_enabled: the organization does not have form comparisons. download_restricted: a file may not be downloaded. forbidden: the credential cannot call this operation. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '404': description: 'not_found: a file does not exist or is not visible to you.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: Use application/json. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: Unexpected server failure. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '503': description: File storage is unavailable; respect Retry-After (seconds). content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2ValidateFormKnowledgeRequest: type: object properties: files: type: array items: type: string format: uuid description: >- File UUID, e.g. 01a150b0-b6a4-774f-a0e0-ad385dbc5028; normalized to lowercase. example: 01a150b0-b6a4-774f-a0e0-ad385dbc5028 minItems: 1 maxItems: 10 description: >- 1–10 distinct knowledge file IDs, validated together as one set. Each current version is read; each file must be UTF-8 text of at most 1 MiB. required: - files additionalProperties: false V2FormKnowledgeValidation: type: object properties: valid: type: boolean description: True exactly when no diagnostic is an error. entries: type: array items: $ref: '#/components/schemas/V2FormKnowledgeEntry' description: >- Every entry, in request file order then line order. Empty unless valid. diagnostics: type: array items: $ref: '#/components/schemas/V2FormKnowledgeDiagnostic' description: >- Errors and warnings, ordered by file then line. Empty when the set is clean. required: - valid - entries - diagnostics V2CodedError: allOf: - $ref: '#/components/schemas/V2Error' - type: object properties: code: type: string minLength: 1 description: Stable error code. Clients must tolerate unknown future codes. details: type: array items: type: object properties: location: type: string enum: - path - query - header - body path: type: array items: type: string maxLength: 64 maxItems: 12 code: type: string enum: - required - invalid_type - invalid_value - unknown_field message: type: string minLength: 1 maxLength: 200 required: - location - path - code - message minItems: 1 maxItems: 20 description: Bounded safe validation issues; may omit some invalid fields. requestId: type: string minLength: 1 maxLength: 128 description: >- Existing server correlation for this HTTP attempt, when available. dataset: type: string enum: - naic - osha description: Dataset needed for dataset_not_enabled. businessCode: type: string description: The rater’s own refusal code, for business_rejection. violations: type: array items: type: object properties: code: type: string description: Authored or built-in constraint code message: type: string description: Authored message for the failed constraint path: type: string description: Input path of the offending value; empty for the request value: nullable: true description: Offending input value, size-bounded by the runtime constraint: type: string description: The constraint the value failed, as text cite: type: string nullable: true description: >- Filing citation of the constraint, when the source cites one required: - code - message - path - value - constraint - cite additionalProperties: false maxItems: 256 description: >- Each input constraint the submission failed, for invalid_inputs and business_rejection. violationsTruncated: type: boolean description: >- True when the rater reported more violations than violations holds. accessUrl: type: string nullable: true format: uri description: >- Where to add the product to your account, for product_access_required. required: - code V2FormKnowledgeEntry: type: object properties: fileId: type: string description: The knowledge file that defines the entry. contentSha256: type: string description: >- SHA-256 of the file bytes that were validated, as sha256:<64 hex digits>. Pass the same file to a comparison; a changed file must be validated again. entryId: type: string description: Full entry ID, namespace:local-id. type: type: string enum: - concept - definition - guidance description: Entry type. kind: type: string nullable: true enum: - coverage - exposure - party_role - act - loss - claim - benefit - condition - term - null description: Concept kind; null for definitions and guidance. label: type: string description: The entry’s label field, else its heading text. line: type: integer minimum: 1 description: One-based line of the entry’s heading. required: - fileId - contentSha256 - entryId - type - kind - label - line V2FormKnowledgeDiagnostic: type: object properties: severity: type: string enum: - error - warning description: An error makes the set invalid; a warning does not. code: type: string description: >- One of invalid_syntax, invalid_schema, invalid_id, duplicate_id, unresolved_reference, invalid_definition_target, invalid_source, unsourced_definition. unsourced_definition is a warning; the rest are errors. Tolerate unknown future codes. message: type: string description: What is wrong and how to fix it. fileId: type: string description: The file the diagnostic belongs to. entryId: type: string description: >- Full ID of the entry concerned; omitted when the file or entry has no valid ID. line: type: integer minimum: 1 description: One-based line in the file; omitted when no line applies. path: type: array items: type: string description: >- Field path inside the front matter or the entry’s yaml block, e.g. ["connections", "0", "target"]; omitted for structural problems. required: - severity - code - message - fileId V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: 'Effective API key. Send Authorization: Bearer sk-eai-...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.