Documentació

Cerca Arxiu

Escriu per cercar a Arxiu.

Biblioteca de Referència OpenAPI

Utilitzeu fonts de referència OpenAPI revisades.

En aquesta pàgina Secció actual: Propòsit

Propòsit

Aquesta guia és el contracte de descobribilitat per als paquets de referència de Decision Gate basats en OpenAPI. Respon, per a cada paquet:

  1. On és el fitxer OpenAPI canònic?
  2. És escrit a mà o obtingut d’una font superior?
  3. Quin test de sistema imposa la integritat del catàleg offline i del mirall?
  4. On són la documentació de l’API per a lectors humans?

Contracte Canònic

La font de veritat llegible per màquina és:

  • references/openapi/reference_library.json

Validat per esquema:

  • references/openapi/reference_library.schema.json

Cada paquet enumerat allà ha de passar controls de porta dura en:

  • system-tests/src/suites/openapi_reference_library.rs

Catàleg Actual de Paquets

ID del paquetDominiOpenAPI canònicMirallsTest de sistemaDocumentació upstream
courtlistener-legal-citation-v1Verificació de citacions legalsreferences/openapi/courtlistener-legal-citation-v1/openapi.jsonsystem-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json i examples/agentic/legal-citation-verification/courtlistener_reference_openapi.jsonopenapi_reference_library_canonical_and_mirrors_are_byte_equal a system-tests/src/suites/openapi_reference_library.rsVisió general de REST, Cerca de citacions, Arrel de l’API (v4)

Cobertura i Metadades d’Execució

Cada entrada de paquet declara metadades de fixture de recerca:

  1. execution_modes: el mode de catàleg actual suportat és només offline_fixture.
  2. coverage: recomptes deterministes obligatoris:
    • operations
    • fabricated_cases
    • known_good_cases
    • ambiguous_cases
    • invalid_cases
  3. live_mode: només metadades de captura de la font; la política de CI actual és disabled:
    • enabled_by_env
    • required_env
    • optional_env
    • ci_policy (manual_only o disabled)

Per a CourtListener, COURTLISTENER_API_TOKEN pertany només al script de captura de fixtures manual autònom. No és un camí de credencials de temps d’execució de DG, i el paquet no es pot habilitar com a proveïdor a través de la configuració.

Regla d’Autoria de Projecció (Canonical)

La metadada de projecció s’avalua sobre l’esquema de resposta normalitzat/resolt. La metadada de projecció a nivell de component referenciada mitjançant $ref és de primera classe i preferida.

No duplicar esquemes de resposta en línia només per satisfer les comprovacions de l’importador. Mantingueu una ubicació de projecció canònica (normalment l’esquema del component referenciat) i reflectiu això byte per byte a través de còpies de paquets canònics/sistemes/exemples.

Política de Proveniència de Fonts

Per a cada paquet, el catàleg provenance ha de declarar explícitament l’origen:

  • hand_authored_fixture
  • upstream_openapi_snapshot
  • generated_from_upstream_docs

CourtListener actualment utilitza hand_authored_fixture.

Cobertura de Hard-Gate

El CI estàndard imposa portes deterministes fora de línia:

  1. El JSON del catàleg és vàlid segons l’esquema.
  2. Tots els camins catalogats existeixen.
  3. Els artefactes OpenAPI canònics i mirall són iguals en bytes (incloent operation_fixture_corpus.json i fitxers de manifest de captura de font).
  4. El catàleg system_test_name existeix a Docs/generated/testing/proof_catalog.json.
  5. El catàleg docs_paths existeix a Docs/verification/registry.toml.
  6. Les URLs de la font són absolutes https:// i completament de metadades.
  7. La cobertura i les metadades de captura de font són estructuralment vàlides i el CI en viu està desactivat.

No s’executen comprovacions de connectivitat de xarxa en viu en el CI estàndard.

Nova Llista de Comprovació del Paquet (Preparat per PubMed/arXiv)

Utilitzeu aquesta llista de verificació quan afegiu DG + PubMed, DG + arXiv, o similar:

  1. Creeu el directori canònic: references/openapi/<pack-id>/
  2. Afegeix els fitxers canònics:
    • openapi.json
    • citation_cases.json (o corpus determinista equivalent al domini)
    • README.md
  3. Afegeix còpies mirall a:
    • system-tests/tests/fixtures/<domain_pack>/
    • examples/agentic/<domain-pack>/
  4. Afegir/extendre la suite de proves del sistema a system-tests/src/suites/.
  5. Registreu la suite a system-tests/tests/providers.rs.
  6. Actualitzeu la declaració de prova de Rust adjacent a la suite i regeneri system-tests/TEST_MATRIX.md.
  7. Afegiu l’entrada del paquet a references/openapi/reference_library.json.
  8. Assegureu-vos que docs_paths estiguin registrats a Docs/verification/registry.toml.
  9. Inclou enllaços de markdown amb nom a la documentació de l’API a la README del paquet.
  10. Declara execution_modes, coverage i live_mode metadades.

Plantilla de Metadades

{
  "pack_id": "<kebab-case-pack-id>",
  "version": "v1",
  "domain": "<domain>",
  "status": "experimental",
  "provenance": "hand_authored_fixture",
  "canonical_openapi_path": "references/openapi/<pack-id>/openapi.json",
  "system_fixture_openapi_path": "system-tests/tests/fixtures/<pack>/openapi.json",
  "example_openapi_path": "examples/agentic/<pack>/openapi.json",
  "system_suite_path": "system-tests/src/suites/<suite>.rs",
  "system_test_name": "<exact_test_name>",
  "docs_paths": [
    "Docs/guides/openapi_reference_library.md"
  ],
  "upstream_docs": [
    {
      "label": "<human label>",
      "url": "https://...",
      "kind": "rest_overview",
      "verified_on_utc": "2026-02-21"
    }
  ],
  "execution_modes": [
    "offline_fixture"
  ],
  "coverage": {
    "operations": 4,
    "fabricated_cases": 6,
    "known_good_cases": 3,
    "ambiguous_cases": 1,
    "invalid_cases": 1
  },
  "live_mode": {
    "enabled_by_env": "COURTLISTENER_LIVE",
    "required_env": [
      "COURTLISTENER_API_TOKEN"
    ],
    "optional_env": [
      "COURTLISTENER_BASE_URL"
    ],
    "ci_policy": "disabled"
  },
  "notes": "<deterministic note>"
}