Biblioteca de Referència OpenAPI

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:

On és el fitxer OpenAPI canònic?
És escrit a mà o obtingut d’una font superior?
Quin sistema de prova aplica el comportament?
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

Pack ID	Domain	Canonical OpenAPI	Mirrors	System Test	Upstream Docs
`courtlistener-legal-citation-v1`	Verificació de citacions legals	`references/openapi/courtlistener-legal-citation-v1/openapi.json`	`system-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json` i `examples/agentic/legal-citation-verification/courtlistener_reference_openapi.json`	`legal_citation_reference_projection_first_end_to_end` a `system-tests/src/suites/legal_citation.rs`	Visió general de REST, Cerca de citacions, Arrel de l’API (v4)

Cobertura i Metadades d’Execució

Cada entrada de paquet ara declara:

execution_modes: conjunt requerit de offline_fixture i/o live_opt_in.
coverage: required deterministic counts:
- operacions
- casos_fabricats
- casos_bons_coneguts
- casos_ambigus
- casos_invàlids
live_mode: required env + CI policy contract:
- activat_per_env
- required_env
- optional_env
- ci_policy (manual_only o disabled)

Per a CourtListener, required_env està intencionadament buit perquè l’autenticació en temps d’execució utilitza secret://courtlistener/api_token preprovisionat de l’emmagatzematge de secrets xifrats. COURTLISTENER_API_TOKEN només s’utilitza per a les eines manuals de captura de fixtures, no per a l’execució en viu de proves de fum en temps d’execució. Emmagatzema el valor brut del token; la metadada de renderització en temps d’execució tipificada aplica el prefix Token requerit en l’autenticació sortint. Quan el keyring no està disponible/sense capçalera, estableix DECISION_GATE_SECRETS_PASSPHRASE abans dels comandos secrets init/put/list perquè l’emmagatzematge xifrat pugui ser desbloquejat.

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:

màquina_autoria_manual
upstream_openapi_snapshot
generat_dels_docs_upstream

CourtListener actualment utilitza hand_authored_fixture.

Cobertura de Hard-Gate

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

El JSON del catàleg és vàlid segons l’esquema.
Tots els camins catalogats existeixen.
Canonical and mirrored OpenAPI artifacts are byte-equal (including operation_fixture_corpus.json i fitxers de manifest de captura en viu).
El catàleg system_test_name existeix a Docs/generated/testing/proof_catalog.json.
El catàleg docs_paths existeix a Docs/verification/registry.toml.
Les URLs de la font són absolutes https:// i completament de metadades.
La cobertura i la metadada d’execució/en mode viu són estructuralment vàlides.

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:

Create canonical directory: references/openapi/<pack-id>/
Add canonical files:
- openapi.json
- typed_import_payload_example.json
- citation_cases.json (o corpus determinista equivalent al domini)
- README.md
Add mirror copies under:
- system-tests/tests/fixtures/<domain_pack>/
- examples/agentic/<domain-pack>/
Afegir/extendre la suite de proves del sistema a system-tests/src/suites/.
Registreu la suite a system-tests/tests/providers.rs.
Actualitza crates/decision-gate-test-contracts/src/source_catalog.json i system-tests/TEST_MATRIX.md.
Afegiu l’entrada del paquet a references/openapi/reference_library.json.
Assegureu-vos que docs_paths estiguin registrats a Docs/verification/registry.toml.
Inclou enllaços de markdown amb nom a la documentació de l’API a la README del paquet.
Declara execution_modes, coverage i live_mode metadades.

Plantilla de Metadades

{
  "pack_id": "<kebab-case-pack-id>",
  "version": "v1",
  "domain": "<domain>",
  "status": "active",
  "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/decision-gate/guides/openapi-reference-library"
  ],
  "upstream_docs": [
    {
      "label": "<human label>",
      "url": "https://...",
      "kind": "rest_overview",
      "verified_on_utc": "2026-02-21"
    }
  ],
  "execution_modes": [
    "offline_fixture",
    "live_opt_in"
  ],
  "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": [],
    "optional_env": [
      "COURTLISTENER_BASE_URL",
      "COURTLISTENER_LIVE_CASE_LIMIT"
    ],
    "ci_policy": "manual_only"
  },
  "notes": "<deterministic note>"
}