Documentación

Buscar en Arxiu

Escriba para buscar en Arxiu.

Biblioteca de Referencia OpenAPI

Utilice fuentes de referencia de OpenAPI revisadas.

En esta página Sección actual: Propósito

Propósito

Esta guía es el contrato de descubribilidad para los paquetes de referencia de Decision Gate respaldados por OpenAPI. Responde, para cada paquete:

  1. ¿Dónde está el archivo OpenAPI canónico?
  2. ¿Es creado a mano o proviene de una fuente superior?
  3. ¿Qué prueba del sistema hace cumplir la integridad del catálogo y del espejo fuera de línea?
  4. ¿Dónde están los documentos de la API para lectores humanos?

Contrato Canónico

La fuente de verdad legible por máquina es:

  • references/openapi/reference_library.json

Validado por esquema:

  • references/openapi/reference_library.schema.json

Cada paquete listado allí debe pasar controles de puerta dura en:

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

Catálogo Actual de Paquetes

ID del paqueteDominioOpenAPI canónicoEspejosPrueba del sistemaDocumentación upstream
courtlistener-legal-citation-v1Verificación de citas legalesreferences/openapi/courtlistener-legal-citation-v1/openapi.jsonsystem-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json y examples/agentic/legal-citation-verification/courtlistener_reference_openapi.jsonopenapi_reference_library_canonical_and_mirrors_are_byte_equal en system-tests/src/suites/openapi_reference_library.rsDescripción general de REST, Búsqueda de citas, Raíz de API (v4)

Cobertura y Metadatos de Ejecución

Cada entrada de paquete declara metadatos de investigación de fixture:

  1. execution_modes: el modo de catálogo actualmente soportado es offline_fixture solamente.
  2. coverage: recuentos deterministas obligatorios:
    • operations
    • fabricated_cases
    • known_good_cases
    • ambiguous_cases
    • invalid_cases
  3. live_mode: solo metadatos de captura de la fuente; la política de CI actual es disabled:
    • enabled_by_env
    • required_env
    • optional_env
    • ci_policy (manual_only o disabled)

Para CourtListener, COURTLISTENER_API_TOKEN pertenece solo al script de captura de fixture manual independiente. No es una ruta de credenciales de tiempo de ejecución de DG, y el paquete no se puede habilitar como proveedor a través de la configuración.

Regla de Autorización de Proyección (Canónica)

Los metadatos de proyección se evalúan en el esquema de respuesta normalizado/resuelto. Los metadatos de proyección a nivel de componente referenciados a través de $ref son de primera clase y preferidos.

No duplique esquemas de respuesta en línea solo para satisfacer las verificaciones del importador. Mantenga una ubicación de proyección canónica (generalmente el esquema de componente referenciado) y refleje eso byte por byte en las copias de paquetes canónicos/sistema/ejemplo.

Política de Procedencia de la Fuente

Para cada paquete, el catálogo provenance debe declarar explícitamente el origen:

  • hand_authored_fixture
  • upstream_openapi_snapshot
  • generated_from_upstream_docs

CourtListener actualmente utiliza hand_authored_fixture.

Cobertura de Hard-Gate

La CI estándar impone puertas deterministas fuera de línea:

  1. El JSON del catálogo es válido según el esquema.
  2. Todos los caminos catalogados existen.
  3. Los artefactos OpenAPI canónicos y reflejados son byte-iguales (incluyendo operation_fixture_corpus.json y archivos de manifiesto de captura de origen).
  4. El catálogo system_test_name existe en Docs/generated/testing/proof_catalog.json.
  5. El catálogo docs_paths existe en Docs/verification/registry.toml.
  6. Las URL de upstream son absolutas https:// y completas en metadatos.
  7. La cobertura y los metadatos de captura de origen son estructuralmente válidos y CI en vivo está deshabilitado.

No se realizan verificaciones de conectividad de red en vivo en la CI estándar.

Nueva Lista de Verificación de Paquete (Listo para PubMed/arXiv)

Utiliza esta lista de verificación al agregar DG + PubMed, DG + arXiv, o similar:

  1. Crear directorio canónico: references/openapi/<pack-id>/
  2. Añade los archivos canónicos:
    • openapi.json
    • citation_cases.json (o corpus determinista equivalente al dominio)
    • README.md
  3. Añade copias espejo en:
    • system-tests/tests/fixtures/<domain_pack>/
    • examples/agentic/<domain-pack>/
  4. Agregar/extender la suite de pruebas del sistema en system-tests/src/suites/.
  5. Registrar la suite en system-tests/tests/providers.rs.
  6. Actualice la declaración de prueba de Rust adyacente a la suite y regenere system-tests/TEST_MATRIX.md.
  7. Agregar entrada de paquete a references/openapi/reference_library.json.
  8. Asegúrese de que docs_paths estén registrados en Docs/verification/registry.toml.
  9. Incluya enlaces de markdown nombrados a la documentación de la API upstream en el README del paquete.
  10. Declare execution_modes, coverage y live_mode metadata.

Plantilla de Metadatos

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