OPENVIST RECIPES

Validate and summarize recent filings in a saved SEC submissions JSON

Python

Read a saved SEC submissions JSON file, validate the parallel recent-filing arrays for form, filing date, accession number and primary document, then print aligned records or a clear validation error.

The SEC documents that a submissions response keeps recent filing history in compact columnar arrays, and Python 3.12 documents the standard JSON decoder needed to read a saved response. This offline recipe checks that the four requested arrays are present and equally long before pairing their entries. It does not contact the SEC or infer anything about a company or product.

Before you start

Intended runner: Python 3.12; no third-party packages or network access are required. This is not a claim of a tested minimum Python version.
Provide a local UTF-8 JSON file or pipe JSON to stdin using `-`; the input must represent an SEC submissions object with `filings.recent`.
For non-empty records, each selected array entry must be a string. The code does not validate date formats, accession-number formats, or document names beyond that type check.

Build and check

Save the proposed code as `sec_recent.py`.
Create a small synthetic JSON fixture using the four arrays shown in `example_input`.
Run the fixture with `python3.12 sec_recent.py fixture.json` and check that each output row keeps the fields from the same array index together.
Run the same fixture through stdin with `python3.12 sec_recent.py - < fixture.json` and compare the output.
Change one array to a different length and confirm the program rejects it rather than pairing incomplete rows.
Set all four arrays to empty lists and confirm it prints the explicit empty-record message.

Limits to understand

Only summarizes `filings.recent`; it does not read older filing-history files mentioned by SEC documentation.
This offline processor does not establish whether a saved response is current, complete, authentic, or actually retrieved from the SEC.
The recipe rejects unequal array lengths and non-string values in records, but does not impose additional SEC schema rules.
A missing file, unreadable file, malformed JSON, missing object path, missing array, or invalid record produces an error on stderr and exit status 2.
There are no network calls, so no timeout or retry behavior applies.
The Python JSON documentation cautions that parsing untrusted, very large JSON can consume significant CPU and memory; use appropriately bounded local input.

What this example adds

This provides a small, local integrity check for SEC submissions data: it verifies the four parallel arrays before aligning them, handles a valid empty recent list explicitly, and reports malformed input on stderr with a nonzero exit. It summarizes only the requested filing fields; it does not fetch data, modify any service, or make company or product inferences.

Run it

Run with Python 3.12: `python3.12 sec_recent.py saved-submissions.json`. To read from stdin, use `python3.12 sec_recent.py - < saved-submissions.json`.

Example input

{"filings":{"recent":{"form":["10-K","8-K"],"filingDate":["2025-02-20","2025-03-01"],"accessionNumber":["0000000000-25-000001","0000000000-25-000002"],"primaryDocument":["annual.htm","event.htm"]}}}

Expected output

Recent filing records: 2
1. 10-K | 2025-02-20 | 0000000000-25-000001 | annual.htm
2. 8-K | 2025-03-01 | 0000000000-25-000002 | event.htm

INSPECT THE SCRIPT

Inspect, copy and run the documented checks.

This browser preview builds code locally. It does not contact an API or run the code.

Default example ready.

Python example

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 OpenViST contributors
import argparse
import json
import sys
from pathlib import Path

FIELDS = ("form", "filingDate", "accessionNumber", "primaryDocument")


def fail(message):
    print(f"error: {message}", file=sys.stderr)
    raise SystemExit(2)


def main():
    parser = argparse.ArgumentParser(
        description="Validate and summarize recent filings in a saved SEC submissions JSON file."
    )
    parser.add_argument("file", help="saved JSON path, or - to read JSON from stdin")
    args = parser.parse_args()

    try:
        if args.file == "-":
            text = sys.stdin.read()
        else:
            text = Path(args.file).read_text(encoding="utf-8")
    except (OSError, UnicodeError) as exc:
        fail(f"cannot read input: {exc}")

    try:
        document = json.loads(text)
    except json.JSONDecodeError as exc:
        fail(f"invalid JSON at line {exc.lineno}, column {exc.colno}")

    if not isinstance(document, dict):
        fail("top-level JSON value must be an object")
    filings = document.get("filings")
    if not isinstance(filings, dict):
        fail("filings must be an object")
    recent = filings.get("recent")
    if not isinstance(recent, dict):
        fail("filings.recent must be an object")

    arrays = {}
    for field in FIELDS:
        value = recent.get(field)
        if not isinstance(value, list):
            fail(f"filings.recent.{field} must be an array")
        arrays[field] = value

    lengths = {field: len(values) for field, values in arrays.items()}
    if len(set(lengths.values())) != 1:
        detail = ", ".join(f"{field}={lengths[field]}" for field in FIELDS)
        fail(f"recent filing arrays have unequal lengths ({detail})")

    count = lengths["form"]
    if count == 0:
        print("No recent filing records.")
        return

    print(f"Recent filing records: {count}")
    for index in range(count):
        values = [arrays[field][index] for field in FIELDS]
        if not all(isinstance(value, str) for value in values):
            fail(f"record {index + 1} contains a non-string field")
        form, filing_date, accession, primary_document = values
        print(f"{index + 1}. {form} | {filing_date} | {accession} | {primary_document}")


if __name__ == "__main__":
    main()

What to verify after running

Use a normal synthetic fixture with two rows; verify the four displayed fields remain aligned by index and the count is two.
Use a fixture whose four arrays are all empty; verify `No recent filing records.` is printed.
Use a fixture with unequal array lengths; verify an error identifies the observed lengths and no filing summary is printed.
Use malformed JSON and a top-level JSON array; verify each is rejected with an actionable error.
Use a fixture with a missing array and another with a non-string record field; verify both are rejected.
Pass a nonexistent path; verify a read error is reported and the process exits nonzero.

Request or format preview

Illustrative preview. No provider response, price or balance is fetched.

Change a setting to inspect the preview.

Official sources and related profiles

Code license: MIT. Keep the license notice with your copy.

Example version 0.1.0 · Documentation reviewed 2026-10-11.

Executed 6 synthetic local fixture cases in isolated CPython 3.12.15 on GitHub Actions, without network access. Declared exit codes, output assertions and input integrity checks passed. Live services, installed third-party packages and production behavior remain outside scope. Editorial approval is still required.