Validierungs-API

OSCAL-1.2.2-JSON-Dokumente per HTTP validieren — zustandslos, anonym, mit derselben Engine wie der Browser-Validator.

Die Secani OSCAL Validierungs-API validiert OSCAL-1.2.2-JSON-Dokumente per HTTP. Sende das Dokument selbst als Request-Body per POST — ohne Umschlag, ohne Konto — und erhalte einen maschinenlesbaren Bericht von derselben Engine, die auch den Browser-Validator antreibt. Die API ist für Maschinen im Arbeitsfluss gebaut: CI-Jobs, Integrationsskripte und andere Werkzeuge, die OSCAL-Dokumente erzeugen oder transformieren.

Datenschutz-Zusage. Dein Dokument wird flüchtig im Arbeitsspeicher auf EU-Servern (Frankfurt) verarbeitet und mit dem Senden der Antwort verworfen. Nichts wird gespeichert, protokolliert oder für etwas anderes als die Antwort verwendet; Telemetrie ist ausschließlich aggregiert (Modelltyp, Größenklasse, Ergebnis, Dauer). Der Browser-Validator bleibt vollständig browser-lokal — dort verlässt dein Dokument den Browser nie.

Schnellstart

curl -sS -X POST https://secani.com/api/oscal/v1/validate \
  -H "content-type: application/json" \
  --data-binary @system-security-plan.json

Große Artefakte (vollständige Catalogs können das 4-MB-Limit für unkomprimierte Bodies überschreiten) lassen sich hervorragend komprimieren — sende sie gezippt:

gzip -c catalog.json | curl -sS -X POST https://secani.com/api/oscal/v1/validate \
  -H "content-type: application/json" \
  -H "content-encoding: gzip" \
  --data-binary @-

Antwort

Eine abgeschlossene Validierung liefert immer HTTP 200 — "valid": false ist die erfolgreiche Validierung eines ungültigen Dokuments. Verzweige auf dem Feld valid, nicht auf dem Statuscode.

{
  "valid": false,
  "model": "system-security-plan",
  "oscalVersion": "1.2.2",
  "level": "schema",
  "issues": [
    {
      "path": "/system-security-plan/metadata/version",
      "message": "must have required property 'version'",
      "keyword": "required",
      "severity": "error"
    }
  ],
  "issueCount": 37,
  "truncated": false,
  "meta": {
    "engine": "@secani/oscal",
    "schemaSource": "NIST OSCAL v1.2.2 release JSON schemas",
    "patches": ["profile-combine-method"],
    "durationMs": 84
  }
}

Feld	Bedeutung
`valid`	Ob das Dokument die Schema-Validierung bestanden hat.
`model`	Erkanntes OSCAL-Modell (eines der acht OSCAL-1.2.2-Modelle).
`oscalVersion`	Die im Metadaten-Block deklarierte `oscal-version`; `unknown`, wenn sie fehlt.
`level`	Ausgeführte Validierungsstufe. In v1 immer `schema`.
`issues[].path`	RFC-6901-JSON-Pointer in das eingereichte Dokument.
`issues[].severity`	In v1 immer `error`; `warning` ist für künftige interpretative Regeln reserviert.
`issueCount`	Tatsächliche Gesamtzahl der Feststellungen, auch wenn `issues` gekürzt ist.
`truncated`	`true`, wenn mehr als 200 Feststellungen gefunden und die Liste gekappt wurde.
`meta.patches`	Dokumentierte Abweichungen von den rohen NIST-Release-Schemas.

Fehler

Fehler verwenden RFC-9457-Problem-Details (application/problem+json) mit einem stabilen maschinenlesbaren code:

Status	Code	Bedeutung
400	`ERR_INVALID_JSON`	Der Body ist kein wohlgeformtes JSON.
400	`ERR_UNKNOWN_MODEL`	JSON, aber kein erkennbares OSCAL-Wurzelmodell.
400	`ERR_INVALID_CONTENT_ENCODING`	`Content-Encoding: gzip` deklariert, aber der Body ist kein gültiges gzip.
400	`ERR_UNSUPPORTED_PARAMETER`	Ein reservierter Query-Parameter trägt einen noch nicht unterstützten Wert.
405	`ERR_METHOD_NOT_ALLOWED`	Nur POST (und OPTIONS) werden akzeptiert.
413	`ERR_PAYLOAD_TOO_LARGE`	Unkomprimierter Body über 4 MB oder dekomprimierter Body über 24 MB.
415	`ERR_UNSUPPORTED_MEDIA_TYPE`	Anderer Content-Type als `application/json` oder ein nicht unterstütztes Encoding.
429	`ERR_RATE_LIMITED`	Rate-Limit überschritten; siehe `Retry-After`.
500	`ERR_INTERNAL`	Unerwarteter Fehler; es werden keine Interna offengelegt.

Limits

Request-Body: 4 MB unkomprimiert, 24 MB dekomprimiert (Content-Encoding: gzip wird unterstützt und für große Dokumente empfohlen).
Ein Dokument pro Request.
Anonyme Rate-Limits: 10 Requests pro Minute und 300 pro Tag je Client, ausgewiesen über die Response-Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, mit Retry-After bei 429-Antworten. Du brauchst mehr? Schreib an hello@secani.com.

Reservierte Parameter

Die folgenden Query-Parameter sind Teil des Vertrags, werden aber abgelehnt, bis ihre Funktionalität verfügbar ist. Ein nicht unterstützter Wert liefert ERR_UNSUPPORTED_PARAMETER mit einer Erklärung:

level — heute nur schema. Eine tiefere Stufe mit Constraint- und Referenzprüfungen auf Basis von Secanis erweiterter Validierungs-Registry ist geplant.
rules — reserviert für das Zuschalten einzelner interpretativer Regeln zusammen mit der tieferen Stufe.
oscal-version — heute nur 1.2.2.

API-Schlüssel mit höheren, verlässlichen Rate-Limits sind geplant; die anonyme Stufe bleibt bestehen.

OpenAPI

Der maschinenlesbare Vertrag wird unter /api/oscal/v1/openapi.json ausgeliefert. CORS ist offen (*), die API lässt sich also direkt aus browserbasierten Werkzeugen aufrufen.

Siehe auch: der Browser-Validator für die interaktive Nutzung und das TypeScript-Toolkit hinter beiden.